Next.js Production-Ready Template

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.

🎯 Philosophy

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.

✨ Features

Core Stack

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

Testing Infrastructure

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

Code Quality Tools

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

Database & Infrastructure

PostgreSQL - Production-ready relational database
Docker Compose - Containerized development and test databases
Prisma migrations - Version-controlled database schema
Environment management - Secure configuration with .env files

📋 Prerequisites

Node.js 20.x or higher
npm 10.x or higher
Docker and Docker Compose (for database)
Git for version control

🚀 Getting Started

1. Clone and Install

# Clone the repository
git clone https://github.com/alexfdez1010/next-template.git my-project
cd my-project

# Install dependencies
npm install

2. Environment Setup

# Copy environment template
cp .env.example .env

# Edit .env with your configuration
# DATABASE_URL="postgresql://postgres:postgres@localhost:5432/db"

3. Database Setup

# Start PostgreSQL container
npm run database

# Run migrations (in another terminal)
npm run database:dev

# Stop database when done
npm run database:down

4. Run Development Server

# Start development server with Turbopack
npm run dev

Open http://localhost:3000 to see your application.

📜 Available Scripts

Development

npm run dev - Start development server with database
npm run build - Build production bundle
npm run start - Start production server
npm run launch - Build and start with database

Code Quality

npm run lint - Run ESLint and Prisma formatting
npm run format - Format code with Prettier
npm run lint-format - Lint and format (required before commits)
npm run pre-commit - Run tests and code quality checks

Testing

npm test - Run all tests (unit, integration, E2E)
npm run test:unit - Run unit tests only
npm run test:integration - Run integration tests only
npm run test:e2e - Run E2E tests with Playwright
npm run playwright - Open Playwright UI for debugging

Database

npm run database - Start PostgreSQL container
npm run database:down - Stop database container
npm run database:dev - Run migrations in development
npm run database:deploy - Deploy migrations to production
npm run database:studio - Open Prisma Studio
npm run database:test - Start test database

🏗️ Project Structure

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

🧪 Testing Strategy

Unit Tests

Located in tests/unit/, these test individual functions and components in isolation.

npm run test:unit

Integration Tests

Located in tests/integration/, these test module interactions and API endpoints.

npm run test:integration

End-to-End Tests

Located in tests/e2e/, these test complete user flows across browsers.

npm run test:e2e

🗄️ Database Management

Prisma Workflow

# Create a new migration
npm run database:dev

# Deploy migrations to production
npm run database:deploy

# Check migration status
npm run database:check

# Open Prisma Studio
npm run database:studio

Schema Changes

Edit prisma/schema.prisma
Run npm run database:dev to create migration
Test with npm run database:test
Commit schema and migration files

🚢 Deployment

Environment Variables

Ensure all required environment variables are set:

DATABASE_URL="postgresql://user:password@host:5432/database"

Build and Deploy

# Build production bundle
npm run build

# Run production server
npm run start

🔧 Configuration Files

tsconfig.json - TypeScript strict mode, path aliases
eslint.config.mjs - Next.js and TypeScript rules
.prettierrc - Single quotes, trailing commas, 2-space tabs
vitest.config.ts - Node environment, 10s timeout
playwright.config.ts - Multi-browser E2E testing

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.vscode		.vscode
prisma		prisma
public		public
src/app		src/app
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
README.md		README.md
compose-test.yml		compose-test.yml
compose.yml		compose.yml
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

alexfdez1010/next-template

Folders and files

Latest commit

History

Repository files navigation