Production-ready Next.js monorepo with Clean Architecture and Domain-Driven Design
A comprehensive starter template implementing Clean Architecture and DDD patterns. Built with Next.js 16, TypeScript, Turborepo, Drizzle ORM, and a complete DDD toolkit. Designed for scalable enterprise applications with AI-friendly codebase architecture.
Built with Claude Code | Documentation | Features | Quick Start
- Clean Architecture - Separation of concerns with clear layer boundaries
- Domain-Driven Design - Comprehensive DDD toolkit with Entities, Value Objects, Aggregates
- Result Pattern - Type-safe error handling without exceptions
- Option Pattern - Eliminate null/undefined with functional patterns
- Use Cases - Encapsulated business logic following single responsibility
- Domain Events - Event-driven architecture with type-safe handlers
- Next.js 16 - App Router, React Server Components, Server Actions
- TypeScript 5.9 - Strict mode with comprehensive type safety
- Turborepo - High-performance build system for monorepos
- Drizzle ORM - Type-safe SQL with PostgreSQL
- shadcn/ui - Beautiful, accessible component system
- Tailwind CSS 4 - Modern utility-first CSS framework
- Biome - Fast linter and formatter (replaces ESLint + Prettier)
- Vitest - Lightning-fast unit testing
- PNPM - Efficient package management
- Claude Code Integration - Optimized for AI-assisted development
- Comprehensive Documentation - CLAUDE.md with full codebase context
- .cursorrules - AI coding guidelines and patterns
- VS Code Configuration - Pre-configured for optimal AI assistance
- Helper Scripts - Generate Value Objects, Use Cases, and more
cleanstack/
├── apps/
│ └── nextjs/ # Main Next.js application
│ ├── app/ # App Router pages & layouts
│ ├── common/ # DI container, translations, providers
│ └── src/ # Clean Architecture layers
│ ├── adapters/ # Controllers, presenters, repositories
│ ├── application/ # Use cases & business logic
│ ├── domain/ # Entities, value objects, aggregates
│ └── infrastructure/ # Database, external APIs
├── packages/
│ ├── ddd-kit/ # DDD primitives (Entity, ValueObject, Aggregate, Result, Option)
│ ├── drizzle/ # Database schema & migrations
│ ├── ui/ # shadcn/ui components + brutalist design system
│ └── test/ # Shared test utilities
CleanStack follows Clean Architecture with strict dependency rules:
Infrastructure → Adapters → Application → Domain
↓ ↓ ↓
Database Controllers Use Cases Entities & Value Objects
External Presenters Aggregates & Events
APIs Repositories
Dependencies flow inward only. The domain layer has zero external dependencies.
- Node.js ≥ 24.12.0
- PNPM 10.26.2
- Docker & Docker Compose
# 1. Clone and install dependencies
git clone https://github.com/axelhamil/nextjs-clean-architecture-starter cleanstack
cd cleanstack
pnpm install
# 2. Setup database
cp .env.example .env
docker-compose up -d
pnpm db:push
# 3. Start development server
pnpm devVisit http://localhost:3000 to see your app.
- Read CLAUDE.md - Comprehensive guide to the architecture
- Check .cursorrules - AI coding guidelines and patterns
- Explore @packages/ddd-kit - Learn the DDD primitives
- Try helper scripts - Generate Use Cases and Value Objects
| Service | URL |
|---|---|
| Next.js | http://localhost:3000 |
# Development
pnpm dev # Start development server
pnpm build # Build for production
pnpm start # Start production server
# Code Quality
pnpm validate # Full validation (type-check + lint + test)
pnpm quick-check # Fast check (type-check + lint)
pnpm type-check # TypeScript type checking
pnpm check # Biome lint & format check
pnpm format # Format code with Biome
pnpm test # Run all tests with Vitest
# Database
pnpm db # Start PostgreSQL container
pnpm db:push # Push schema changes
pnpm db:generate # Generate migrations
pnpm db:migrate # Run migrations
pnpm db:studio # Open Drizzle Studio
# Utilities
pnpm clean # Clean build artifacts
pnpm ui:add # Add shadcn/ui components- CLAUDE.md - Complete architecture guide and codebase context
- .cursorrules - AI coding guidelines and architectural patterns
- @packages/ddd-kit - DDD primitives documentation
const emailOrError = Email.create("user@example.com");
if (emailOrError.isFailure) {
return Result.fail(emailOrError.getError());
}
const email = emailOrError.getValue();export class Email extends ValueObject<EmailProps> {
protected validate(props: EmailProps): Result<EmailProps> {
if (!emailRegex.test(props.value)) {
return Result.fail("Invalid email");
}
return Result.ok(props);
}
}export class CreateUserUseCase implements UseCase<CreateUserInput, User> {
async execute(input: CreateUserInput): Promise<Result<User>> {
// Business logic here
}
}CleanStack is optimized for AI coding assistants:
- CLAUDE.md provides complete codebase context
- .cursorrules defines architectural patterns and anti-patterns
- Helper scripts generate boilerplate code
- Comprehensive comments in DDD primitives
- Open CLAUDE.md in your AI assistant
- Ask it to read .cursorrules for coding guidelines
- Use helper scripts:
./scripts/create-use-case.sh MyUseCase - Follow Result and Option patterns consistently
Perfect for:
- Enterprise applications requiring maintainable architecture
- Scalable systems with complex business logic
- Teams wanting clear architectural boundaries
- AI-assisted development with Claude Code or Cursor
- Long-term projects where testability matters
Not ideal for:
- Simple CRUD apps or MVPs
- Prototypes requiring rapid iteration
- Projects with minimal business logic
Contributions are welcome! Please read CLAUDE.md to understand the architecture before submitting PRs.
MIT © AxelHamil
Built with Claude Code | Give it a ⭐ if you find it useful!