Next.js DDD CLI Tool 🚀

A powerful command-line interface for generating Domain-Driven Design (DDD) domains with progressive complexity levels, Swagger integration, and full-stack capabilities for Next.js applications.

✨ Features

• 🏗️ Progressive Complexity: Start simple, grow complex as needed (4 levels)
• 📄 Swagger Integration: Generate domains from OpenAPI/Swagger docs
• 🎯 Full-Stack Generation: Complete domain with UI, tests, and docs
• 💎 Value Objects: Built-in DDD value objects with validation
• 🧪 Testing Ready: Comprehensive test suites (unit, integration, E2E)
• 🎨 Modern UI: TailwindCSS, Chakra UI, Material UI support
• 📖 Documentation: Auto-generated docs and Storybook stories
• ⚡ Performance: Built-in optimizations and best practices

Installation

npm install -g  
# or
yarn global add nextjs-ddd-cli
# or
pnpm add -g nextjs-ddd-cli

Usage

Setup Project Utilities (NEW! 🆕)

Bootstrap your Next.js project with essential utility libraries and custom hooks:

nextjs-ddd-cli setup
# or with force flag to overwrite existing files
nextjs-ddd-cli setup --force

This will generate:

• lib/ - Essential utility functions (array helpers, object helpers, fetcher, date helpers, etc.)
• hooks/ - Custom React hooks (useDebounce, useEntityTable, useMobile, useInView)
• config/ - NextAuth configuration with custom session tokens
• src/app/ - Complete app structure with protected/unprotected routes
• @types/ - TypeScript type definitions
• constants/ - Application constants and route URLs
• components/ - Shared UI components

App Structure Generated:

• src/app/page.tsx - Root page with auth redirect
• src/app/(protected)/ - Protected routes requiring authentication
• src/app/(unprotected)/ - Public routes (login, register, etc.)
• src/app/api/auth/[...nextauth]/ - NextAuth API routes

Generate a New Domain

Create a new domain with Level 1 (CRUD) structure:

nextjs-ddd-cli generate <domain-name>
# or
nextjs-ddd-cli g <domain-name>

# Example
nextjs-ddd-cli generate products

Options:

• -d, --description <desc> - Domain description
• -p, --path <path> - Custom domains path (default: src/domains)

Add Complexity to Existing Domain

Upgrade a domain to a higher complexity level:

nextjs-ddd-cli add-complexity <domain-name> --level <2-4>
# or
nextjs-ddd-cli ac <domain-name> -l <2-4>

# Example
nextjs-ddd-cli add-complexity products --level 2

List All Domains

View all domains and their current complexity levels:

nextjs-ddd-cli list
# or
nextjs-ddd-cli ls

Generate Full-Stack Domain (NEW! 🆕)

Create a complete full-stack domain with advanced features:

nextjs-ddd-cli generate-full-stack <domain-name>
# or
nextjs-ddd-cli gfs <domain-name>

# Example
nextjs-ddd-cli gfs products

This command provides an interactive setup for:

• Complexity Level: Choose from 4 progressive levels
• UI Framework: React with TailwindCSS, Chakra UI, Material UI, or Ant Design
• Features: Tests, docs, authentication, performance optimizations
• Advanced Tools: Storybook stories, E2E tests with Playwright

Generate Module from Swagger/OpenAPI

Generate a complete DDD module from Swagger/OpenAPI documentation:

nextjs-ddd-cli add-module-swagger <swagger-url>
# or
nextjs-ddd-cli ams <swagger-url>

# Examples
nextjs-ddd-cli ams https://petstore.swagger.io/v2/swagger.json
nextjs-ddd-cli ams ./api-docs/swagger.json

This command will:

• Parse Swagger documentation and extract available modules
• Generate complete TypeScript types from schemas
• Create service layer with all CRUD operations
• Generate React Query hooks for data fetching
• Create React components and pages with modern UI
• NEW: Include value objects for domain modeling
• Include comprehensive tests and documentation

Options:

• -p, --path <path> - Custom domains path (default: src/domains)

Enhanced Features:

• ✅ Full CRUD operation detection (GET, POST, PUT, PATCH, DELETE)
• ✅ TypeScript type generation from Swagger schemas
• ✅ Request/response type extraction
• ✅ Query parameter and filter type generation
• ✅ React Query integration with proper caching
• ✅ Module update detection and smart merging
• ✅ NEW: Value objects (Status, Email, ID) generation
• ✅ NEW: Enhanced UI components with TailwindCSS
• ✅ NEW: Comprehensive form handling with react-hook-form + Zod
• ✅ Comprehensive error handling and validation

Complexity Levels

Level 1: Simple CRUD (Default)

• Basic types and interfaces
• Simple service layer
• API integration
• React hooks
• UI components
• Page components

Level 2: Business Rules

• Value objects
• Validation services
• Business rules
• Domain-specific errors

Level 3: Domain Models

• Domain entities
• Aggregate roots
• Domain services
• Repository pattern
• Specifications
• Factories

Level 4: Workflows & Events

• Complex workflows
• Domain events
• Event handlers
• Application services
• Command/Query pattern
• Facades for UI

Example Workflow

1. Create a new domain:

   nextjs-ddd-cli generate orders

2. Start developing with basic CRUD operations

3. Add validation and business rules when needed:

   nextjs-ddd-cli add-complexity orders --level 2

4. Introduce rich domain models:

   nextjs-ddd-cli add-complexity orders --level 3

5. Add complex workflows and events:

   nextjs-ddd-cli add-complexity orders --level 4

Generated Structure

Level 1 Structure

orders/
├── models/
│   ├── order.types.ts
│   └── order.schema.ts
├── services/
│   └── order.service.ts
├── api/
│   ├── order.api.ts
│   ├── order.queries.ts
│   └── order.mutations.ts
├── hooks/
│   ├── useOrders.ts
│   ├── useOrder.ts
│   └── useOrderMutations.ts
├── components/
│   ├── OrderList.tsx
│   ├── OrderCard.tsx
│   ├── OrderForm.tsx
│   └── OrderFilters.tsx
├── pages/
│   ├── OrdersPage.tsx
│   ├── OrderDetailPage.tsx
│   └── OrderEditPage.tsx
└── README.md

Additional Folders per Level

Level 2 adds:

• value-objects/ - Domain value objects
• errors/ - Domain-specific errors

Level 3 adds:

• entities/ - Domain entities
• repositories/ - Repository interfaces
• infrastructure/ - Technical implementations
• specifications/ - Business specifications
• factories/ - Entity factories

Level 4 adds:

• workflows/ - Complex business workflows
• events/ - Domain events
• facades/ - Simplified API for UI
• application/ - Application services

Configuration

Create a .dddrc.json file in your project root for default settings:

{
  "domainsPath": "src/domains",
  "includeTests": true,
  "includeApi": true,
  "defaultLevel": 1
}

Development

Building the CLI

cd packages/cli
npm install
npm run build

Testing Locally

npm link
nextjs-ddd-cli --help

License

MIT