nest-forge

nest-forge

Generate fully-structured NestJS client SDK modules from OpenAPI specs (JSON or YAML). Point it at a spec, get a production-ready NestJS module with typed service, Zod validation, injectable routes, and dynamic module configuration.

Built on top of orval with a custom NestJS builder and post-processing pipeline.

Claude Code Integration

nest-forge ships as a Claude Code plugin with an SDK generator skill that walks you through the entire workflow -- from finding an OpenAPI spec to wiring the generated module into your app.

Install the plugin

# Add the marketplace
claude plugin marketplace add romtaugranot/nest-forge

# Install the plugin
claude plugin install nest-forge-sdk

Once installed, Claude Code will automatically suggest using nest-forge-sdk when you're integrating with an external API or mention OpenAPI specs. You can also invoke the skill directly:

/nestjs-sdk-generator

What the skill does

1. Helps you obtain an OpenAPI spec (finds published specs, or builds a minimal one from API docs)
2. Installs nest-forge-sdk and peer dependencies
3. Runs the generator with appropriate tag filtering
4. Wires the generated module into your NestJS app using your preferred configuration pattern (ConfigModule, environment variables, etc.)
5. Verifies the integration compiles and shows usage examples

Table of Contents

• Claude Code Integration
• Features
• Installation
• Quick Start
• What Gets Generated
• Using the Generated Module
• How It Works
• CLI Reference
• Programmatic API
• Requirements
• Contributing
• License

Features

• Full NestJS module with forRoot / forRootAsync dynamic configuration
• Zod schema validation on every response via safeParse
• Typed route map with template parameters for parameterized URLs, injectable and overridable through the module
• Tag filtering -- generate only a subset of a large API with --tags or --exclude-tags
• Schema batching -- schemas and types grouped by OpenAPI tag into combined files, with unused schemas pruned automatically
• Split file structure following NestJS conventions: schemas/, types/, exceptions/, interfaces/, data/, utils/
• Kebab-case file naming derived automatically from the OpenAPI spec title
• Automatic operation naming -- derives method names from HTTP verb + route path when operationId is missing
• Controller prefix stripping from operation names (SessionController_createSession becomes createSession)
• Custom exception classes extending NestJS HttpException with proper Axios error wrapping
• Zero runtime dependencies in the generated SDK beyond @nestjs/common, axios, and zod
• Zero hardcoded URLs in the service -- all routes come from an injectable route map

Installation

npm install -D nest-forge-sdk

The generated code requires these peer dependencies in your project:

npm install @nestjs/common axios zod

Quick Start

CLI

# Minimal -- output goes to current directory
npx nest-forge-sdk ./openapi.json

# YAML support
npx nest-forge-sdk ./openapi.yaml

# Specify output directory
npx nest-forge-sdk --input ./openapi.yml --output ./libs

# Generate only specific tags
npx nest-forge-sdk ./openapi.yaml --tags endpoint,user

# Exclude specific tags
npx nest-forge-sdk ./openapi.yaml --exclude-tags admin,internal

Programmatic

import { generate } from 'nest-forge-sdk';

await generate({
  input: './openapi.json', // JSON and YAML both supported
  outputDir: './libs',
  tags: ['endpoint', 'user'], // optional: include only these tags
});

What Gets Generated

Given an OpenAPI spec with info.title: "user-service", nest-forge produces: