nod-cli

Backend scaffolding CLI for Node.js with best practices built-in. Generate production-ready Express or Hono projects with TypeScript, authentication, database connections, AI features, and more.

Installation

corepack prepare pnpm@11.5.0 --activate
pnpm add -g nod-cli

Quick Start

# Create a new project (interactive)
nod init my-api

# Or use shorthand
nod my-api

# Non-interactive default: strict production API (TypeScript by default)
nod init my-api --yes

# One-command AWS SAM backend
nod backend my-api

# Strict SAM backend with shared Postgres rate limits
nod init my-api --preset aws-sam-backend --rate-limit-store postgres --yes

# Or pick a specific preset
nod init my-api --preset 1 --framework express --yes

# Non-interactive with JavaScript
nod init my-api --preset api --no-ts --yes

# Follow the interactive prompts to configure:
# - Preset (production-api, aws-sam-backend, minimal, api, full, ai, 1, or custom presets)
# - Framework (Express/Hono)
# - TypeScript/JavaScript
# - Database (PostgreSQL/MySQL/Supabase/None)
# - ORM (Drizzle/Raw SQL)
# - Authentication (JWT/JWKS/Supabase/Better Auth/None)
# - AI features (RAG, Chat, Langfuse)
# - Deployment (AWS SAM, Vercel cron, GitHub workflow)
# - Rate limit store (Postgres, Redis, None)
# - Docker & PM2 configuration

Presets

Preset	Description
`production-api`	Default strict API: Supabase, Drizzle, Better Auth, Postgres-backed rate limits, trusted origins, Lambda/SAM
`aws-sam-backend`	Production AWS SAM backend: Express, TypeScript, Supabase/Drizzle, Better Auth, static Drizzle rate limits, strict security, pnpm dependency layer, Node 22 Lambda
`minimal`	Basic setup, no database or auth
`api`	Standard REST API with JWT auth
`full`	All features including Supabase, Drizzle, Vercel cron
`ai`	Full preset + RAG, Chat, Langfuse
`1`	Supabase + Drizzle + API Audit + GitHub Actions
`custom`	Choose your own features

Custom Presets

Create and manage your own presets:

# List all presets
nod preset list

# Create a custom preset
nod preset create mystack

# Set default preset
nod preset default mystack

# Show preset details
nod preset show mystack

# Delete a custom preset
nod preset delete mystack

Custom presets are stored in ~/.nod-cli/presets.json and can be used like built-in presets:

nod init my-api --preset mystack --yes

Commands

Initialize Project

nod init <project-name>
# or shorthand
nod <project-name>

Create AWS SAM Backend

nod backend <project-name>

This is shorthand for a production AWS SAM backend preset with Express, TypeScript, strict security, Supabase/Drizzle, Better Auth, Postgres-backed rate limits, a pnpm-built dependency layer, Node.js 22 Lambda, template.yaml, samconfig.toml, and docs/aws-sam-setup.md.

Options

Option	Description	Default
`--framework <framework>`	Web framework: `express` or `hono`	`express`
`--ts`	Use TypeScript	`true`
`--no-ts`	Use JavaScript instead of TypeScript	-
`--db <database>`	Database: `pg`, `mysql`, `supabase`, or `none`	`pg`
`--auth <auth>`	Auth: `jwt`, `jwks`, `supabase`, `cookie-session`, `better-auth`, or `none`	preset
`--queue <queue>`	Queue: `bull` or `none`	`none`
`--preset <preset>`	Use a preset configuration	`production-api` in non-interactive mode
`--security <mode>`	Security: `basic` or `strict`	preset
`--deploy-target <target>`	Deploy target: `node` or `lambda-sam`	preset
`--cron <boolean>`	Include node/Lambda cron support	preset
`--vercel-cron <boolean>`	Include Vercel cron config	preset
`--rate-limit-store <store>`	Rate limit store: `postgres`, `redis`, or `none`	`postgres` for strict Drizzle/SAM
`-y, --yes`	Skip prompts, use defaults	-

Examples

# Interactive mode
nod init my-api

# TypeScript with preset 1 (non-interactive)
nod my-api --preset 1 --yes

# JavaScript project with API preset
nod init my-api --preset api --no-ts --yes

# Hono framework with Supabase
nod init my-api --framework hono --db supabase --auth supabase --yes

# Minimal JavaScript project
nod my-api --preset minimal --no-ts --yes

Add Components

Navigate to your project directory first:

cd my-api

Then add components:

# Add route with controller and service
nod add route users

# Add complete auth module
nod add auth

# Add shared-store rate limiter (Postgres preferred)
nod add middleware --name rateLimit --type rateLimit --rate-limit-store postgres --yes

# Add Redis-backed rate limiter
nod add middleware --name rateLimit --type rateLimit --rate-limit-store redis --yes

# Add CORS middleware and apply globally
nod add cors

# Add service
nod add service email

# Add cron job support
nod add cron

# Add PM2 configuration
nod add pm2

# Add Vercel cron setup
nod add vercel-cron

# Add GitHub Actions workflow for Vercel deployment
nod add github-actions

# Add RAG service
nod add rag

# Add Chat service
nod add chat

# Add Supabase helper
nod add supabase

# Add Drizzle ORM
nod add drizzle

# Add Langfuse
nod add langfuse

Transform Existing Project

Add nod features to an existing project:

nod transform

Select features to add:

Environment Config (staging/production)
Supabase Helper
Drizzle ORM Setup
Supabase JWT Auth Middleware
Vercel Cron Setup
GitHub Workflow
RAG Service
Chat Service
Langfuse Integration
Error Handler
Winston Logger
Response Formatter

Manage Presets

nod preset list              # List all presets
nod preset create [name]     # Create a new preset
nod preset delete [name]     # Delete a custom preset
nod preset default [name]    # Set default preset
nod preset show <name>       # Show preset details

Validate Project

nod validate

Run MCP Server

Run a built-in local MCP server over stdio:

nod mcp

This exposes MCP tools:

nod_help - quick command usage examples
nod_run - execute nod commands locally (init/add/transform/validate/preset)

Example Claude Desktop configuration:

{
  "mcpServers": {
    "nod-cli": {
      "command": "nod",
      "args": ["mcp"]
    }
  }
}

Project Structure

Generated projects follow this structure:

my-api/
├── src/
│   ├── routes/          # Route definitions
│   ├── controllers/     # Request handlers
│   ├── services/        # Domain services (e.g. user.service.ts)
│   ├── middleware/      # Custom middleware
│   ├── auth/            # Auth services (nod add auth)
│   ├── config/          # App configuration
│   ├── helpers/         # Reusable helpers (e.g. user.helper.ts)
│   ├── utils/           # Utility modules (logger, etc.)
│   ├── db/              # Database connection & schema
│   ├── environments/    # Staging/production configs
│   ├── cron/            # Cron jobs
│   └── types/           # TypeScript types (TS only)
├── docs/                # Project documentation & plans
│   └── README.md        # Documentation index
├── temp/                # Temporary output files (git-ignored)
├── sql/                 # SQL schema files
├── .github/             # GitHub workflows
├── .env.example         # Environment variables template
├── .gitignore
├── package.json
├── tsconfig.json        # TypeScript config (TS only)
├── tsconfig.build.json  # TypeScript emit config for non-SAM TS projects
├── tsconfig.lambda.json # TypeScript emit config for SAM TS projects
├── scripts/             # SAM build and runtime import checks (AWS SAM backend)
├── drizzle.config.ts    # Drizzle config (if using Drizzle)
├── template.yaml        # AWS SAM template (if using AWS SAM)
├── samconfig.toml       # AWS SAM deploy profiles (if using AWS SAM)
├── vercel.json          # Vercel config (if using Vercel cron)
├── Dockerfile           # Docker config (if enabled)
├── docker-compose.yml   # Docker Compose (if enabled)
├── ecosystem.config.js  # PM2 config (if enabled)
└── README.md            # Project README

Special Folders

Folder	Purpose
`docs/`	Project documentation, architecture decisions, API docs, and development plans. Committed to git.
`temp/`	Temporary output files (PDFs, exports, generated files). Git-ignored.

Configuration Options

Option	Choices	Description
Framework	Express, Hono	Web framework
TypeScript	Yes, No	Type safety (use `--no-ts` for JavaScript)
Database	PostgreSQL, MySQL, Supabase, None	Database driver
ORM	Drizzle, Raw SQL, None	ORM choice
Auth	JWT, JWKS, Supabase, None	Authentication method
Cron	Yes, No	Scheduled jobs support
Environments	Yes, No	Staging/production config
RAG	Yes, No	Vector search & retrieval
Chat	Yes, No	Conversation management
Langfuse	Yes, No	LLM observability
Vercel Cron	Yes, No	Vercel cron configuration
Rate Limit Store	Postgres, Redis, None	Shared rate-limit storage
GitHub Workflow	Yes, No	CI/CD workflow
Docker	Yes, No	Container configuration
PM2	Yes, No	Process manager config

Features

Core

Declarative Routes - Clean, configuration-based route definitions
Type Safety - Full TypeScript support (or plain JavaScript with --no-ts)
PM2 Cluster Mode - Thread-safe cron jobs with distributed locking
Shared Rate Limits - Postgres/Drizzle by default, Redis when selected
Docker Ready - Dockerfile and docker-compose included
Zod Validation - Runtime config validation (TypeScript only)
Documentation Folder - Built-in docs/ folder for project documentation
Temp Output Folder - Git-ignored temp/ folder for generated files

Database

Supabase Integration - Full Supabase client with storage helpers
Drizzle ORM - Type-safe ORM with connection pooler support
Environment Config - Separate staging/production configurations

Authentication

Complete Auth Module - nod add auth generates JWKS, JWT, password hashing, Google OAuth, forgot password, email service
Supabase JWT Auth - JWKS-based JWT verification using jose library
Custom JWT - Roll your own tokens with auto-generated RSA keys
Password Hashing - Bcrypt-based password hashing with strength validation
Google OAuth - Server-side token verification
Permission Middleware - Role-based access control from JWT payload

AI Features

RAG Service - Vector similarity search with OpenAI embeddings
Chat Service - Conversation management with LangChain
Langfuse - Optional LLM observability and tracing

Deployment

AWS SAM - Lambda/API Gateway backend with TypeScript ESM .js emit and a pnpm-built dependency layer
Vercel Cron - Cron job configuration with auth middleware
GitHub Workflow - Deploy trigger workflow

AWS SAM Backend Pattern

Generated SAM backends use ESM .js files under "type": "module". They do not emit .mjs.

The Lambda build is deliberately split:

dist/ contains TypeScript-emitted application code and Lambda handlers.
dist-layer/ contains production node_modules installed with pnpm.
template.yaml attaches the dependency layer to every function and uses BuildMethod: makefile.
scripts/check-sam-runtime-imports.js imports every built handler after sam build --parallel.

This avoids standalone bundler failures from hidden dynamic imports such as packages that compute import('drizzle-orm') at runtime. Postgres rate limits use generated static Drizzle SQL instead of rate-limiter-flexible's Drizzle adapter. Redis rate limits still use rate-limiter-flexible.

Generated Drizzle clients are Lambda-safe by default: prepare: false, DATABASE_POOL_MAX=2, DATABASE_CONNECT_TIMEOUT_SECONDS=5, DATABASE_IDLE_TIMEOUT_SECONDS=20, and DATABASE_MAX_LIFETIME_SECONDS=1800. Use an RDS Proxy or database pooler URL for Lambda.

Generated API audit middleware skips GET, HEAD, and OPTIONS DB writes. Use ALB/API Gateway/WAF/access logs for read-path traffic and keep DB audit rows for mutations or explicit domain events.

Running Your Project

cd my-api
pnpm install
cp .env.example .env
# Edit .env with your settings
pnpm dev

Available Scripts

Script	Description
`pnpm dev`	Start development server with hot reload
`pnpm build`	Build for production (TypeScript only)
`pnpm start`	Start production server
`pnpm lint`	Lint code with ESLint
`pnpm format`	Format code with Prettier
`pnpm test`	Run tests (if testing enabled)

Production

pnpm build
pm2 start ecosystem.config.js

PM2 Commands

pnpm start:pm2    # Start with PM2
pnpm stop:pm2     # Stop PM2 processes
pnpm restart:pm2  # Restart PM2 processes
pnpm logs:pm2     # View PM2 logs
pnpm monit:pm2    # Monitor PM2 processes

Drizzle Commands

pnpm db:generate  # Generate migrations
pnpm db:migrate   # Apply migrations
pnpm exec drizzle-kit migrate --config=<drizzle.config.ts|drizzle.config.js>  # Apply migrations
pnpm db:studio    # Open Drizzle Studio

CI/CD & Non-Interactive Mode

For CI/CD pipelines, use the --yes flag to skip all prompts:

# In CI environment
nod init my-api --preset api --yes

# With specific options
nod init my-api --preset 1 --framework express --no-ts --yes

The CLI also respects the CI environment variable - when CI=true, it automatically uses non-interactive mode.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
test-scripts		test-scripts
website		website
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
schema.json		schema.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation