Back

Hexogen

A CLI tool for generating CRUD APIs with hexagonal architecture in NestJS applications. It creates complete, production-ready APIs using Hygen templates.

Tech Stack :
Source Code
|
Live Demo
Hexogen
šŸš€ Build CRUD APIs instantly ā€” no hallucinations, just real code, faster and more reliable than AI āš”

Table of Contents

Why Hexogen?

Building CRUD APIs with proper hexagonal architecture is time-consuming and error-prone. You need to create controllers, services, repositories, DTOs, entities, mappers, and modules ā€” all following specific patterns and best practices.
Hexogen solves this problem by automatically generating complete, production-ready CRUD APIs with hexagonal architecture in NestJS applications. Instead of manually creating all the boilerplate code, you can generate entire API modules with a single command.
Build CRUD APIs with hexagonal architecture ā€” effortlessly and reliably.

Perfect For

šŸŽ“ Junior Developers

  • Learn by doing: Generate proper CRUD APIs with hexagonal architecture without needing to understand all the concepts upfront
  • Best practices built-in: All generated code follows industry standards and patterns
  • Gradual learning: Start with generated APIs and gradually understand the architecture as you work with it
  • No architectural decisions: Focus on business logic while the tool handles the API structure

šŸš€ Developers Who Want Good Architecture Without Complexity

  • Simple setup: No complex boilerplates with overwhelming configurations
  • Minimal learning curve: Get started immediately without weeks of setup and configuration
  • Clean foundation: Start with a clean NestJS project and add CRUD APIs with hexagonal architecture as needed
  • No over-engineering: Avoid advanced boilerplates that include features you don't need yet
  • Gradual adoption: Add architectural patterns incrementally as your project grows

šŸ—ļø Teams Starting New Projects

  • Consistent structure: Everyone follows the same patterns from day one
  • Scalable foundation: Start simple and scale up as your application grows
  • Reduced setup time: Get from zero to production-ready CRUD APIs in minutes, not days
  • Team productivity: Spend time on features, not on architectural setup and configuration
Hexogen bridges the gap between simple CRUD applications and enterprise-grade architecture, making professional patterns accessible to developers at all levels.

Prerequisites

Before using hexogen, ensure your NestJS project has the following dependencies and setup:

Required Dependencies

Project Setup

  1. NestJS Project: A properly configured NestJS application
  2. TypeORM: Configured with your database connection
  3. Swagger: Set up for API documentation
  4. Validation: Class-validator and class-transformer for DTO validation
  5. Decorators: Ensure
    is imported in your main.ts

Quick Start with Demo Project

For a complete setup example with all prerequisites configured, check out our demo project:
nestjs-hexogen-starter - A complete NestJS project with all required dependencies pre-configured, ready to use with hexogen for CRUD API generation.
This starter project includes:
  • āœ… NestJS with TypeORM configuration
  • āœ… Swagger/OpenAPI setup
  • āœ… Class-validator and class-transformer
  • āœ… Database connection examples
  • āœ… Ready-to-use project structure
No hexagonal architecture setup required - just install hexogen and start generating CRUD APIs. The package will automatically create the hexagonal architecture structure for you.

About Hexagonal Architecture

Hexogen generates code following Hexagonal Architecture (also known as Ports and Adapters), a powerful architectural pattern that provides excellent separation of concerns, testability, and maintainability.

Features

Hexogen provides a comprehensive set of features to make hexagonal architecture implementation seamless and efficient:

šŸš€ Complete Module Generation

Generate entire hexagonal architecture modules with a single command. Includes controllers, services, repositories, DTOs, entities, mappers, and modules following NestJS best practices.
Usage:

šŸ“ Interactive Property Addition

Add new properties to existing modules with interactive prompts. Automatically updates DTOs, entities, and mappers across all layers.
Usage:

šŸ”„ Sub-Entity Generation

Create sub-entities within existing modules, maintaining proper hexagonal architecture structure and relationships.
Usage:

šŸ“Š Versioned Resource Support

Generate versioned resources with proper API versioning structure, including version-specific controllers and DTOs.
Usage:

šŸŽÆ Schema-Driven Generation

Generate modules from JSON schema files, automatically creating all necessary files based on your data model.
Usage:

šŸ”§ TypeORM Integration

Built-in support for TypeORM with proper entity definitions, repository patterns, and database integration.

šŸ“š Swagger/OpenAPI Ready

All generated DTOs include Swagger decorators for automatic API documentation generation.

āœ… Validation Pipes

Generated DTOs include comprehensive validation using class-validator decorators.

šŸŽØ Automatic Prettier Formatting

All generated files are automatically formatted using Prettier for consistent code style.

šŸ”— Relative Path Imports

No dependency on project path configuration - all imports use relative paths for better portability.

šŸ“¦ Common Utilities

Automatic copying of pagination utilities and common DTOs to your project for consistent patterns.

šŸ“‹ Template Listing

View all available templates and their descriptions to understand what can be generated.
Usage:

šŸ” Interactive Prompts

All commands use interactive prompts when parameters are missing, making the tool user-friendly and intuitive.

šŸ›”ļø Error Handling

Robust error handling with graceful fallbacks for missing dependencies like Prettier.

Installation

Global Installation (Recommended)

After installation, you can use the CLI from any directory:

Local Development

  1. Clone the repository
  2. Install dependencies:
  1. Link the package for local development:

Usage

Generate a New Module/Resource

Using JSON Schema Files

To avoid interactive prompts, you can provide a JSON schema file using the
option. This allows for automated generation and CI/CD integration.

Resource Schema Format

Create a JSON file (e.g., user-schema.json) with the following structure:
Schema Fields:
  • : The resource name (e.g., "User", "Product")
  • : Whether to generate test files (true/false)
  • : Array of CRUD operations to generate (create, findAll, findOne, update, delete)
  • : Array of entity properties
Field Properties:
  • : Property name (e.g., "first_name", "age")
  • : Whether the field is optional (true/false)
  • : Database type (varchar, int, boolean, json, etc.)
  • : Custom TypeScript type (leave empty for standard types)
  • : Example value for Swagger documentation
  • : Whether to include this field in DTOs (true/false)

Sub-Entity Schema Format

Create a JSON file (e.g.,
) with the following structure:
Schema Fields:
  • : The parent resource name (e.g., "User")
  • : The sub-entity name (e.g., "Address", "Profile")
  • : Array of entity properties (same structure as resource fields, but without the
    property)
Usage Examples:

Add a Property to a Module

List Available Templates

Custom Templates

Hexogen supports custom templates stored in a
folder in your project root. This allows you to create project-specific templates that extend the built-in functionality.

List Custom Templates

Run Custom Templates

Custom Template Structure

Create a
folder in your project root with the following structure:
Template Categories:
  • - For generating new resources/modules
  • - For adding properties to existing modules
  • - For generating sub-entities
  • - For generating versioned resources
  • Any other category you prefer
Template Requirements:
  • Each template must have a
    file
  • Follow Hygen template structure and conventions
  • Use the same parameter names as built-in templates for consistency

Benefits of Custom Templates

  • Project-specific patterns: Create templates tailored to your project's conventions
  • Team consistency: Share templates across your team
  • Extended functionality: Add features not available in built-in templates
  • Version control: Track template changes with your project
  • Easy maintenance: Update templates without affecting the global installation

Show Help and Usage Examples

Options:
  • : Path to schema JSON file for entity definition
  • : Skip Prettier formatting after generation (useful for large projects)

Error Handling

  • All commands provide clear success/failure messages.
  • Interactive prompts guide you through the process when parameters are missing.

Supported Templates

Available Templates:
  • resource
  • subentity
  • versioned
  • property

Project Structure

Inspiration

Hexogen was inspired by the excellent implementation of hexagonal architecture in the realworld-nestjs-medium-blog project. This project demonstrates a complete Medium clone backend using NestJS, TypeORM, and hexagonal architecture patterns, serving as a real-world example of how these architectural principles can be applied to build production-ready APIs.
The realworld-nestjs-medium-blog project showcases:
  • Complete CRUD operations with hexagonal architecture
  • TypeORM integration with PostgreSQL
  • Comprehensive testing (unit and E2E)
  • Swagger documentation
  • Docker and CI/CD setup
  • Real-world API patterns and best practices
We've taken inspiration from this project's architectural decisions and patterns to create Hexogen, making it easier for developers to implement similar hexagonal architecture patterns in their own NestJS applications.

Contributing

Please check out our contributing guidelines and get in touch!

Contact

Please feel free to reach out:
I look forward to hearing from you!

License

This project is licensed under MIT Ā© Ahmad Bilal

Support

For issues, questions and suggestions, please open an issue on the GitHub repository.