nx-nest-ddd

A comprehensive Nx plugin for generating Domain-Driven Design (DDD) architecture with NestJS. This plugin provides powerful generators for building scalable, maintainable applications following DDD principles, Clean Architecture, and CQRS patterns.

🚀 Features

• 🏗️ Complete DDD Architecture: Generate domain, application, infrastructure, and UI layers with a single command
• ⚡ CQRS Support: Built-in command and query generators with proper separation
• 🧹 Clean Architecture: Proper separation of concerns across architectural layers
• 🪶 NestJS Integration: Seamless integration with NestJS framework and ecosystem
• 🔌 Multiple UI Options: Support for both REST and GraphQL API interfaces
• 🛡️ Type Safety: Full TypeScript support with proper typing and interfaces
• 📦 Modular Design: Generate individual components or complete bounded contexts
• 🧪 Testing Ready: Includes test structure and e2e test applications
• 📖 Best Practices: Follows industry standards and DDD patterns

📦 Installation

Install the plugin in your Nx workspace:

npm install --save-dev @hatung/nx-nest-ddd
# or
yarn add --dev @hatung/nx-nest-ddd
# or
pnpm add --save-dev @hatung/nx-nest-ddd

🎯 Quick Start

Generate a complete DDD bounded context in seconds:

nx g @hatung/nx-nest-ddd:sub-domain my-feature

This creates a fully functional DDD architecture with API, libraries, and tests ready to use!

⚙️ Generator Options

Most generators accept common options to customize the generated code:

Common Options

• --subDomain - The sub-domain that contains the component (required for most generators)
• --sourceRoot - Override the default directory location
• --templatePath - Use custom templates for generation

Sub-Domain Generator Options

• --directory - Directory where the application is placed
• --tags - Add tags for linting (e.g., "domain:users,layer:api")
• --strict - Enable TypeScript strict mode (default: true)
• --target - ES target version (default: es2021)
• --testEnvironment - Jest test environment: "node" or "jsdom"
• --skipFormat - Skip formatting files
• --skipPackageJson - Don't add dependencies to package.json

Properties Support

Many generators support defining properties for entities and value objects:

String Format (recommended for CLI)

--propertiesString="name:string,email:string,isActive:boolean:true"

JSON Array Format

--properties='[{"name":"title","type":"string"},{"name":"price","type":"number"},{"name":"available","type":"boolean","optional":true}]'

Property Format

• name:type - Required property
• name:type:true - Optional property (third parameter indicates optional)
• Supported types: string, number, boolean, Date, custom types

📚 Usage

🏛️ Generate a Complete Sub-Domain

Create a complete bounded context with all layers:

# Basic sub-domain
nx g @hatung/nx-nest-ddd:sub-domain my-feature

# Sub-domain with custom options
nx g @hatung/nx-nest-ddd:sub-domain users --tags="domain:users,layer:api" --directory=business

# Sub-domain with TypeScript strict mode disabled
nx g @hatung/nx-nest-ddd:sub-domain orders --strict=false --target=es2020

This command creates a complete Domain-Driven Design structure with the following components and folders:

Applications Generated:

• apps/<domain-name>/api/ - NestJS API application
• apps/<domain-name>/api-e2e/ - End-to-end tests for the API

Libraries Generated:

• libs/<domain-name>/domain/ - Domain layer with:

  • src/aggregates/ - Domain aggregates and root entities
  • src/entities/ - Domain entities
  • src/events/ - Domain events
  • src/exceptions/ - Domain-specific exceptions
  • src/repositories/ - Repository interfaces
  • src/services/ - Domain services

• libs/<domain-name>/application/ - Application layer with:

  • src/commands/ - CQRS command handlers
  • src/queries/ - CQRS query handlers
  • src/events/ - Application event handlers
  • src/modules/ - Application modules

• libs/<domain-name>/infrastructure/ - Infrastructure layer with:

  • src/repositories/ - Repository implementations
  • src/orm-entities/ - Database entities
  • src/orm-mappers/ - Domain-to-ORM mappers
  • src/modules/ - Infrastructure modules

• libs/<domain-name>/graphql-ui/ - GraphQL API layer with:

  • src/modules/ - GraphQL modules
  • src/queries/ - GraphQL query resolvers
  • src/mutations/ - GraphQL mutation resolvers
  • src/types/ - GraphQL type definitions

• libs/<domain-name>/rest-ui/ - REST API layer with:

  • src/controllers/ - REST controllers
  • src/dto/ - Data Transfer Objects
  • src/modules/ - REST modules

🏗️ Generate Domain Layer Components

Build your domain layer with core business logic:

# Domain entity - Core business objects with properties
nx g @hatung/nx-nest-ddd:domain-entity user users --propertiesString="name:string,email:string,isActive:boolean:true"

# Domain entity with individual properties array
nx g @hatung/nx-nest-ddd:domain-entity product catalog --properties='[{"name":"title","type":"string"},{"name":"price","type":"number"},{"name":"available","type":"boolean","optional":true}]'

# Value object - Immutable domain concepts with properties
nx g @hatung/nx-nest-ddd:domain-value-object email users --propertiesString="value:string"

# Domain aggregate - Consistency boundaries
nx g @hatung/nx-nest-ddd:domain-aggregate order orders --propertiesString="customerId:string,totalAmount:number,status:OrderStatus"

# Domain service - Business logic that doesn't fit in entities
nx g @hatung/nx-nest-ddd:domain-service user-service users

# Domain event - Business events for decoupling
nx g @hatung/nx-nest-ddd:domain-event user-created users

# Domain repository interface - Data access contracts
nx g @hatung/nx-nest-ddd:domain-repository user-repository users

⚡ Generate Application Layer Components

Implement use cases and CQRS patterns:

# Application layer - Complete application services
nx g @hatung/nx-nest-ddd:application user

# CQRS Commands - Write operations with sub-domain
nx g @hatung/nx-nest-ddd:application-command create-user users
nx g @hatung/nx-nest-ddd:application-command update-user users --sourceRoot=libs/users/application

# CQRS Queries - Read operations with sub-domain
nx g @hatung/nx-nest-ddd:application-query get-user users
nx g @hatung/nx-nest-ddd:application-query find-users users --sourceRoot=libs/users/application

# Application events - Cross-cutting concerns
nx g @hatung/nx-nest-ddd:application-event user-processed users

🔧 Generate Infrastructure Layer Components

Handle persistence and external concerns:

# Infrastructure layer - Complete infrastructure setup
nx g @hatung/nx-nest-ddd:infrastructure user

# ORM entities - Database representations
nx g @hatung/nx-nest-ddd:infrastructure-orm-entity user

# ORM mappers - Domain to database mapping
nx g @hatung/nx-nest-ddd:infrastructure-orm-mapper user

# Repository implementations - Data access implementations
nx g @hatung/nx-nest-ddd:infrastructure-repository user-repository

🌐 Generate UI Layer Components

Create API interfaces for external communication:

# REST API - HTTP endpoints
nx g @hatung/nx-nest-ddd:rest-ui user
nx g @hatung/nx-nest-ddd:rest-controller user

# GraphQL API - GraphQL schema and resolvers
nx g @hatung/nx-nest-ddd:graphql-ui user
nx g @hatung/nx-nest-ddd:graphql-query get-user
nx g @hatung/nx-nest-ddd:graphql-mutation create-user

🏛️ Architecture Overview

This plugin implements a clean, layered architecture following DDD principles:

┌─────────────────────────────────────────────────────────────┐
│                        🌐 UI Layer                           │
│              REST Controllers | GraphQL Resolvers          │
├─────────────────────────────────────────────────────────────┤
│                   ⚡ Application Layer                       │
│        Commands | Queries | Event Handlers | Use Cases     │
├─────────────────────────────────────────────────────────────┤
│                     🏗️ Domain Layer                          │
│    Entities | Aggregates | Value Objects | Domain Services │
├─────────────────────────────────────────────────────────────┤
│                  🔧 Infrastructure Layer                     │
│     Repositories | ORM Entities | External Services        │
└─────────────────────────────────────────────────────────────┘

Layer Responsibilities

• 🌐 UI Layer: API contracts, request/response handling, authentication
• ⚡ Application Layer: Business workflows, CQRS implementation, transaction boundaries
• 🏗️ Domain Layer: Core business rules, domain logic, business invariants
• 🔧 Infrastructure Layer: Data persistence, external integrations, technical concerns

📋 Requirements

• Node.js >= 18
• Nx >= 21.0.0
• NestJS project structure
• TypeScript enabled

🛠️ Development

Building

nx build nx-nest-ddd

Running Tests

nx test nx-nest-ddd

Local Development

# Link for local development
npm link

# Use in another project
npm link @hatung/nx-nest-ddd

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🔄 Open a Pull Request

Development Guidelines

• Follow existing code patterns and conventions
• Add tests for new generators
• Update documentation for new features
• Ensure all tests pass before submitting

📝 Changelog

v1.1.0

• 📚 Enhanced README with comprehensive generator options and properties documentation
• ⚙️ Added detailed examples for using properties in entity and value object generation
• 🎯 Improved architectural diagrams and visual explanations
• 🛠️ Added development guidelines and contribution instructions
• ✨ Better CLI examples with real-world usage patterns
• 📖 Documented all available generator options and their usage

v1.0.0

• Initial release with complete DDD generators
• Support for Domain, Application, Infrastructure, and UI layers
• CQRS command and query generators
• REST and GraphQL API generators

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with ❤️ by the NWS-AI-Codex team
• Inspired by Domain-Driven Design principles by Eric Evans
• Powered by Nx and NestJS