npm.io
1.0.0 • Published yesterdayCLI

nestcraftx

Licence
MIT
Version
1.0.0
Deps
2
Size
610 kB
Vulns
0
Weekly
0
Stars
3
SummaryDependencyVersions

NestCraftX — Clean Architecture Generator for NestJS

NPM Version NPM Downloads License: MIT Node.js Version

ORMs: Prisma TypeORM Mongoose

NestCraftX is a modern and powerful Node.js CLI for automatically generating NestJS projects and content with a clean, maintainable, and production-ready architecture.

It scaffolds everything you need to get started:

  • Modules, Controllers & Services (Fully typed)
  • Repositories & Mappers (For clean data flow and separation of concerns)
  • DTOs (With built-in validation)
  • Entities / Schemas (Prisma, TypeORM, or Mongoose)
  • Authentication (JWT with Refresh Tokens & auto-generated secrets)
  • DevOps Ready (Docker, Docker-Compose & Swagger UI)

It implements modern best practices: Clean Architecture, Domain-Driven Design (DDD), Prisma/TypeORM/Mongoose, JWT Auth with auto-generated secrets, Swagger, Docker, and much more.

Key Features:

  • Dual-Architecture: Choose between Light (MVP) or Full (Clean Architecture / DDD).

  • Interactive Relations: Define 1-N or N-N relationships directly in the terminal.

  • Smart Config: Automated Swagger decorators, auto-documented .env files, and pre-configured database connections.

Version 1.0.0 (Stable Release): Production-grade NestJS scaffolding with Clean Architecture, JWT authentication, relations updater, conditional RBAC guards, global rate limiting, health checks, advanced pagination/filtering/sorting, Swagger UI, and Docker compose files!

Table of Contents

What's New in v1.0.0 (Stable Release)

Standalone Relation Command (nestcraftx g relation)
  • Create 1-n, n-1, 1-1, or n-n relations between existing modules at any time.
  • Automatically updates domain entities (FK fields and getters), DTOs (Create and Update), and data mappers.
  • Syncs database schemas (runs format, client generation, and migrations dev for Prisma; injects ObjectId references for Mongoose).
Conditional RBAC Guards & Swagger Integration
  • Mutation endpoints (POST, PATCH, DELETE) are protected with JwtAuthGuard and RolesGuard (@Roles('ADMIN')) only if Auth is enabled.
  • Read endpoints (GET, GET :id) are decorated with @Public().
  • Generates complete API documentation using @ApiBearerAuth() and standard error responses when Swagger is enabled.
Global Rate Limiting (Throttler Module)
  • Integrated @nestjs/throttler package with preconfigured global rate limiting policies (default: 10 requests per minute).
  • Configurable via interactive prompts or CLI flag --throttler.
Health Check Endpoint (/health)
  • Exposes a native /health check route reporting global status (ok), timestamp, and application uptime (process.uptime()).
  • Fully documented in Swagger UI, optimized with zero third-party packages for fast compilation and maximum safety.
Advanced Query Params (Pagination, Filtering, Sorting)
  • Auto-injects paginated data retrieval (e.g. ?page=1&limit=10&search=...&sortBy=createdAt&sortOrder=desc) into controllers and repository layers.
  • Seamlessly maps incoming query params to Prisma, TypeORM, and Mongoose queries.
Interactive Scaffolding Report
  • Out-of-the-box CLI report with ASCII borders after each module generation summarizing files generated, database schema updates, relations established, and clear next steps.
Quick Examples
# LIGHT project with Prisma and Auth
nestcraftx new my-api --light --orm=prisma --auth

# FULL project with TypeORM and Swagger
nestcraftx new my-project --full --orm=typeorm --swagger

# Minimal MongoDB project
nestcraftx new my-api --light --orm=mongoose

Project Objective

Stop wasting time configuring your backend architecture. NestCraftX allows you to:

  • Start a project in minutes instead of days
  • Have a Clean Architecture from the start
  • Standardize your projects with the same best practices
  • Automatically configure DB-ORM and other modules (decorators, authentication, dockerization)
  • Focus on business logic
  • Choose between quick configuration (Light) or complete (Full)

Prerequisites

Make sure you have:

  • Node.js v14 or higher
  • npm or yarn
  • Nest CLI (optional, will be used via npx)
  • Docker (optional, for containerization)
  • Git (optional, for version control)

Verify your environment with:

nestcraftx test

Installation

Via npx (recommended)

Use NestCraftX without global installation:

npx nestcraftx new my-app
Global Installation

For frequent use:

npm install -g nestcraftx
nestcraftx new my-app
Installation for Development
git clone https://github.com/august-dev-pro/NestCraftX.git
cd NestCraftX
npm install
npm link
Running Tests

We use Jest to run unit tests and E2E generator compiler tests:

# Run unit tests (fast check)
npm run test:unit

# Run E2E integration tests (scaffolds project, runs npm install & tsc type checks)
npm run test:e2e

# Run all tests
npm test

Available Commands

nestcraftx new <project-name> [options]

Creates a new NestJS project with Clean Architecture.

Options:

  • --light : Quick configuration mode
  • --orm <prisma|typeorm|mongoose> : ORM choice
  • --auth : Add JWT authentication
  • --swagger : Add Swagger UI
  • --docker : Generate Docker files

Examples:

# Full interactive mode
nestcraftx new my-app

# Quick mode with options
nestcraftx new blog-api --light --orm=prisma --auth --swagger

# Custom configuration
nestcraftx new shop --orm=typeorm --auth
nestcraftx demo [options]

Generates a complete demonstration project (blog-demo) with:

  • 3 entities (User, Post, Comment) with 1-n relationships
  • Integrated JWT Auth
  • Swagger enabled
  • Docker configured

Options:

  • --light : Simplified architecture mode
  • --docker : Enable Docker (default: true)
  • --auth : Enable JWT Auth (default: true)
  • --swagger : Enable Swagger (default: true)
  • --orm <prisma|typeorm|mongoose> : ORM choice (default: prisma)

Examples:

# Interactive mode (will ask questions)
nestcraftx demo

# LIGHT mode with Mongoose
nestcraftx demo --light --orm=mongoose

# FULL mode with TypeORM
nestcraftx demo --orm=typeorm --auth --swagger

# Quick start
nestcraftx demo --light --orm=prisma

Result:

A functional blog project with:

  • Blog-demo created
  • 3 complete entities
  • Relationships between User → Post → Comment
  • Auth endpoints (register, login) ready
  • Business endpoints: /users, /posts, /comments ready
  • Automatic Swagger documentation
  • Docker & Docker Compose configured
  • ORM configuration of your choice (Prisma, TypeORM, Mongoose)
nestcraftx test

Checks if your environment is ready:

nestcraftx test

Displays the status of Node, npm, Nest CLI, Docker, Git, etc.

nestcraftx info

Displays CLI information:

nestcraftx info

Features

Architecture

Clean Architecture with domain/application/infrastructure/presentation separation Domain-Driven Design with entities, use cases and repositories Repository Pattern for persistence abstraction Use Cases Pattern for isolated business logic Mapper Pattern for data transformation

Database

Prisma (PostgreSQL) - Modern and type-safe ORM (recommended)

TypeORM (PostgreSQL) - Complete ORM with decorators

Mongoose (MongoDB) - ODM for MongoDB

Automatic schema configuration

PostgreSQL and MongoDB support

Security

JWT Authentication with guards and strategies

Role-based Access Control (RBAC)

Password hashing with bcrypt

Public routes with decorators

Documentation

Swagger UI automatic

ApiProperty decorators on DTOs

Endpoint documentation

Interactive API interface

DevOps

Docker and Docker Compose

Environment variables configuration

Structured logging

Centralized error handling

Code Quality

DTO validation with class-validator

Data transformation with class-transformer

Standardized response interceptors

Global exception filters

Generated Architecture

Light Mode (MVP)
src
├── auth
│   ├── controllers
│   │   └── auth.controller.ts
│   ├── dtos
│   │   ├── create-session.dto.ts
│   │   ├── forgotPassword.dto.ts
│   │   ├── loginCredential.dto.ts
│   │   ├── refreshToken.dto.ts
│   │   ├── resetPassword.dto.ts
│   │   ├── sendOtp.dto.ts
│   │   └── verifyOtp.dto.ts
│   ├── entities
│   │   └── session.entity.ts
│   ├── guards
│   │   ├── jwt-auth.guard.ts
│   │   └── role.guard.ts
│   ├── mappers
│   │   └── session.mapper.ts
│   ├── persistence
│   │   └── session.repository.ts
│   ├── services
│   │   ├── auth.service.ts
│   │   └── session.service.ts
│   ├── strategies
│   │   └── jwt.strategy.ts
│   └── auth.module.ts
│
├── common
│   ├── decorators
│   │   ├── current-user.decorator.ts
│   │   ├── public.decorator.ts
│   │   └── role.decorator.ts
│   ├── enums
│   │   └── role.enum.ts
│   ├── filters
│   │   └── all-exceptions.filter.ts
│   ├── interceptors
│   │   └── response.interceptor.ts
│   └── middlewares
│       └── logger.middleware.ts
│
├── prisma
│   ├── prisma.module.ts
│   └── prisma.service.ts
│
├── user
│   ├── controllers
│   │   └── user.controller.ts
│   ├── dtos
│   │   └── user.dto.ts
│   ├── entities
│   │   └── user.entity.ts
│   ├── repositories
│   │   └── user.repository.ts
│   ├── services
│   │   └── user.service.ts
│   └── user.module.ts
│
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts
Full Mode (Clean Architecture)
src
├── auth
│   ├── controllers
│   │   └── auth.controller.ts
│   ├── dtos
│   │   ├── create-session.dto.ts
│   │   ├── forgotPassword.dto.ts
│   │   ├── loginCredential.dto.ts
│   │   ├── refreshToken.dto.ts
│   │   ├── resetPassword.dto.ts
│   │   ├── sendOtp.dto.ts
│   │   └── verifyOtp.dto.ts
│   ├── entities
│   │   └── session.entity.ts
│   ├── guards
│   │   ├── jwt-auth.guard.ts
│   │   └── role.guard.ts
│   ├── mappers
│   │   └── session.mapper.ts
│   ├── persistence
│   │   └── session.repository.ts
│   ├── services
│   │   ├── auth.service.ts
│   │   └── session.service.ts
│   ├── strategies
│   │   └── jwt.strategy.ts
│   └── auth.module.ts
│
├── common
│   ├── decorators
│   │   ├── current-user.decorator.ts
│   │   ├── public.decorator.ts
│   │   └── role.decorator.ts
│   ├── enums
│   │   └── role.enum.ts
│   ├── filters
│   │   └── all-exceptions.filter.ts
│   ├── interceptors
│   │   └── response.interceptor.ts
│   └── middlewares
│       └── logger.middleware.ts
│
├── prisma
│   ├── prisma.module.ts
│   └── prisma.service.ts
│
├── user
│   ├── controllers
│   │   └── user.controller.ts
│   ├── dtos
│   │   └── user.dto.ts
│   ├── entities
│   │   └── user.entity.ts
│   ├── repositories
│   │   └── user.repository.ts
│   ├── services
│   │   └── user.service.ts
│   └── user.module.ts
│
├── app.controller.spec.ts
├── app.controller.ts
├── app.module.ts
├── app.service.ts
└── main.ts

Complete Demo

A ready-to-run demo, including 3 linked entities, JWT Auth, Swagger, Docker and configurable ORM.

See full documentation: Demo Documentation

Usage Guide

Quick Start (Light Mode)
# 1. Create a simple project
npx nestcraftx new my-api --light --orm prisma

# 2. Navigate to the project
cd my-api

# 3. Start the application
npm run start:dev
Complete Configuration (Full Mode)
# 1. Launch with interactive interface
npx nestcraftx new my-project

# 2. Answer the questions:
#    - Project name
#    - Database choice
#    - ORM configuration
#    - Entities and relationships
#    - Auth and Swagger

# 3. Start
cd my-project
npm run start:dev
Demonstration Project
# Generate a complete blog project (interactive mode)
nestcraftx demo

# Or with direct options
nestcraftx demo --light --orm prisma --auth --swagger

# Navigate and start
cd blog-demo
npm run start:dev

# Access Swagger UI
open http://localhost:3000/api/docs

What the demo project includes:

  • Complete Clean Architecture (or LIGHT depending on option)
  • 3 pre-configured entities: User, Post, Comment
  • Relationships between entities (User → Post, Post Comment)
  • JWT Auth with /auth/register and /auth/login endpoints
  • Business endpoints: /users, /posts, /comments
  • Automatic Swagger documentation
  • Docker & Docker Compose configured
  • ORM configuration of your choice (Prisma, TypeORM, Mongoose)

Roadmap

Version 0.3.0 — Stabilization & UX (Completed)
  • CommonJS module system unification
  • Dynamic helper versioning and interactive flags checks
  • Dynamic package manager setup
Version 0.4.0 — Architecture Refactoring (Completed)
  • Split of monolithic files into dedicated generators
  • Interactive state-based EntityBuilder with revision menus
  • Dry-run simulation mode (--dry-run)
Version 0.5.0 — Quality & Security (Completed)
  • Persistent DB storage for OTPs & password reset tokens
  • Strict package version pinning
  • Contextual semantic Swagger DTO descriptions
Version 0.6.0 — Tests & CI/CD (Completed)
  • Unit test coverage using Jest
  • E2E compiler checks & resolution of upstream peer dependency conflicts
  • Multi-OS Node.js matrix GitHub Actions CI/CD pipeline
Version 0.7.0 - 0.9.0 — Missing Features (In Progress)
  • Interactive generate auth and complete non-interactive execution
  • API Pagination, filtering, rate limiting, and RBAC guards
  • MySQL/SQLite support
Version 1.0.0 — Stable Release
  • Official documentation website
  • Production audit and LTS guarantees

Contributing

Want to improve NestCraftX? Contributions are welcome!

How to Contribute
  1. Fork the project
  2. Create a branch for your feature (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request
Open an Issue

Found bugs? Have ideas? Open an issue on GitHub!

Developers

To develop locally:

git clone https://github.com/august-dev-pro/NestCraftX.git
cd NestCraftX
npm install
npm link

License

MIT Ablanhou Augustin Selete

Free for personal and commercial use.

Thanks

Thanks to all contributors and the NestJS community!

Made with for the backend developer community

Contact & Support

NestCraftX v0.6.0 - Clean Architecture Made Simple

For more information:

Keywords

nestjsclistartergeneratorclean architecturedddscaffoldprismatypeormmongoosejwtswaggerdockernestjs-cli