A production-grade Next.js template engineered with enterprise-level best practices, comprehensive testing infrastructure, and strict code quality standards. Built for teams that demand excellence in maintainability, scalability, and developer experience. This template is based in the practices used in ZeroChats.
This template embodies professional software engineering principles with a focus on:
- SOLID Principles - Applied rigorously across all code
- Design Pattern Driven - Appropriate patterns for maintainability and scalability
- Documentation First - Comprehensive TSDoc/JSDoc for all functions, classes, and hooks
- Testing as Priority - Unit, integration, and E2E tests with meaningful coverage
- Code Quality - Strict linting, formatting, and file size limits (200 lines max)
- Type Safety - Full TypeScript strict mode enforcement
See AGENTS.md for complete development guidelines and principles that are used to guide AI Agents.
- Next.js 15.5.4 - React framework with App Router
- React 19.1.0 - Latest React with Server Components
- TypeScript 5.x - Strict type safety
- TailwindCSS 4.x - Utility-first CSS framework
- Prisma 6.7.0 - Type-safe database ORM
- Vitest - Fast unit and integration testing
- Playwright - Reliable E2E testing across browsers
- Comprehensive test setup - Separate unit, integration, and E2E test suites
- Docker-based test database - Isolated test environment
- ESLint - Next.js and TypeScript linting rules
- Prettier - Consistent code formatting
- Pre-commit hooks - Automated testing and formatting before commits
- Strict TypeScript - Maximum type safety configuration
- PostgreSQL - Production-ready relational database
- Docker Compose - Containerized development and test databases
- Prisma migrations - Version-controlled database schema
- Environment management - Secure configuration with
.envfiles
- Node.js 20.x or higher
- Bun 1.x or higher (install)
- Docker and Docker Compose (for database)
- Git for version control
# Clone the repository
git clone https://github.com/alexfdez1010/next-template.git my-project
cd my-project
# Install dependencies
bun install# Copy environment template
cp .env.example .env
# Edit .env with your configuration
# DATABASE_URL="postgresql://postgres:postgres@localhost:5432/db"# Start PostgreSQL container
bun run database
# Run migrations (in another terminal)
bun run database:dev
# Stop database when done
bun run database:down# Start development server with Turbopack
bun run devOpen http://localhost:3000 to see your application.
bun run dev- Start development server with databasebun run build- Build production bundlebun run start- Start production serverbun run launch- Build and start with database
bun run lint- Run ESLint and Prisma formattingbun run format- Format code with Prettierbun run lint-format- Lint and format (required before commits)bun run pre-commit- Run tests and code quality checks
bun run test- Run all tests (unit, integration, E2E)bun run test:unit- Run unit tests onlybun run test:integration- Run integration tests onlybun run test:e2e- Run E2E tests with Playwrightbun run playwright- Open Playwright UI for debugging
bun run database- Start PostgreSQL containerbun run database:down- Stop database containerbun run database:dev- Run migrations in developmentbun run database:deploy- Deploy migrations to productionbun run database:studio- Open Prisma Studiobun run database:test- Start test database
next-template/
├── src/
│ └── app/ # Next.js App Router pages
│ ├── layout.tsx # Root layout
│ ├── page.tsx # Home page
│ └── globals.css # Global styles
├── prisma/
│ └── schema.prisma # Database schema
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── e2e/ # End-to-end tests
│ └── setup.ts # Test configuration
├── public/ # Static assets
├── generated/ # Generated Prisma client
├── .vscode/ # VS Code settings
├── compose.yml # Development database
├── compose-test.yml # Test database (ephemeral)
├── eslint.config.mjs # ESLint configuration
├── playwright.config.ts # Playwright configuration
├── vitest.config.ts # Vitest configuration
├── tsconfig.json # TypeScript configuration
├── tailwind.config.ts # TailwindCSS configuration
├── .prettierrc # Prettier configuration
├── .env.example # Environment template
└── AGENTS.md # AI Agents Development guidelines
Located in tests/unit/, these test individual functions and components in isolation.
bun run test:unitLocated in tests/integration/, these test module interactions and API endpoints.
bun run test:integrationLocated in tests/e2e/, these test complete user flows across browsers.
bun run test:e2e# Create a new migration
bun run database:dev
# Deploy migrations to production
bun run database:deploy
# Check migration status
bun run database:check
# Open Prisma Studio
bun run database:studio- Edit
prisma/schema.prisma - Run
bun run database:devto create migration - Test with
bun run database:test - Commit schema and migration files
Ensure all required environment variables are set:
DATABASE_URL="postgresql://user:password@host:5432/database"# Build production bundle
bun run build
# Run production server
bun run starttsconfig.json- TypeScript strict mode, path aliaseseslint.config.mjs- Next.js and TypeScript rules.prettierrc- Single quotes, trailing commas, 2-space tabsvitest.config.ts- Node environment, 10s timeoutplaywright.config.ts- Multi-browser E2E testing
- Next.js Documentation
- React Documentation
- TypeScript Handbook
- TailwindCSS Documentation
- Prisma Documentation
- Vitest Documentation
- Playwright Documentation
This is a template repository. To use it:
- Click "Use this template" on GitHub
- Clone your new repository
- Remove or modify this README as needed
- Start building your application