@bernierllc/nextjs-openapi-suite

Complete Next.js OpenAPI toolkit with CLI and development workflow.

Features

• Complete CLI Tool: Full-featured command-line interface
• Project Initialization: Automated setup for new and existing projects
• Development Workflow: Hot reload, dev server integration
• Build Integration: Automatic generation during Next.js builds
• Configuration Management: Intelligent configuration detection and validation
• Plugin System: Extensible architecture for custom functionality
• Multi-Format Output: JSON, YAML, TypeScript types, and documentation
• NeverHub Integration: Optional event publishing and tracking

Installation

npm install @bernierllc/nextjs-openapi-suite

CLI Usage

Initialize

Initialize OpenAPI suite in a Next.js project:

npx nextjs-openapi-suite init

Generate

Generate OpenAPI specification:

npx nextjs-openapi-suite generate

Watch

Watch for changes and regenerate:

npx nextjs-openapi-suite watch

Build

Build for production:

npx nextjs-openapi-suite build

Validate

Validate configuration:

npx nextjs-openapi-suite validate

Analyze

Analyze Next.js project:

npx nextjs-openapi-suite analyze

Config

Manage configuration:

# Get all config
npx nextjs-openapi-suite config get

# Get specific key
npx nextjs-openapi-suite config get project.root

# List configuration
npx nextjs-openapi-suite config list

# Reset to defaults
npx nextjs-openapi-suite config reset

Programmatic Usage

import { NextJSOpenAPISuite } from '@bernierllc/nextjs-openapi-suite';

// Create suite instance
const suite = new NextJSOpenAPISuite({
  project: {
    root: './my-nextjs-app',
    appDir: 'app',
    pagesDir: 'pages'
  },
  generation: {
    sources: {
      jsdoc: { enabled: true },
      zod: { enabled: true, schemasPath: 'src/schemas' }
    },
    output: {
      json: 'public/openapi.json',
      yaml: 'public/openapi.yaml',
      types: 'src/types/api.d.ts'
    }
  },
  workflow: {
    hotReload: true,
    buildIntegration: true
  }
});

// Initialize
const initResult = await suite.initialize();
console.log('Initialized:', initResult.configPath);

// Generate OpenAPI
const generateResult = await suite.generate();
console.log('Generated:', generateResult.outputFiles);

// Watch for changes
const watcher = await suite.watch({ debounceMs: 1000 });

Configuration

Create nextjs-openapi.config.js in your project root:

module.exports = {
  project: {
    root: __dirname,
    appDir: 'app',
    pagesDir: 'pages',
    name: 'my-api',
    version: '1.0.0'
  },
  generation: {
    sources: {
      jsdoc: {
        enabled: true,
        patterns: ['app/**/*.{ts,tsx}', 'pages/**/*.{ts,tsx}'],
        includeMiddleware: true
      },
      zod: {
        enabled: true,
        schemasPath: 'src/schemas',
        metadataPattern: '*_META'
      }
    },
    output: {
      json: 'public/openapi.json',
      yaml: 'public/openapi.yaml',
      types: 'src/types/api.d.ts',
      docs: 'docs/api'
    },
    merge: {
      strategy: 'merge-deep',
      deduplicateComponents: true
    }
  },
  cli: {
    verbose: true,
    colors: true,
    interactive: true
  },
  workflow: {
    hotReload: true,
    buildIntegration: true,
    gitHooks: {
      preCommit: false,
      prePush: false
    }
  },
  integration: {
    swaggerUI: {
      enabled: true,
      route: '/api-docs'
    },
    redoc: {
      enabled: false
    }
  }
};

Plugin Development

Create custom plugins to extend functionality:

import { NextJSOpenAPIPlugin } from '@bernierllc/nextjs-openapi-suite';

const customPlugin: NextJSOpenAPIPlugin = {
  name: 'custom-validation',
  version: '1.0.0',
  hooks: {
    beforeGenerate: async (context) => {
      console.log('Running custom validation...');
    },
    afterGenerate: async (context, result) => {
      console.log('Post-processing...');
      return result;
    }
  },
  configure: (config) => {
    // Modify configuration
    return config;
  }
};

// Register plugin
suite.registerPlugin(customPlugin);

NeverHub Integration

The suite automatically integrates with NeverHub if available:

• Event publishing for generation events
• Progress tracking
• Error reporting

No configuration needed - detection is automatic.

Requirements

• Node.js >= 18.0.0
• Next.js >= 13.0.0

License

UNLICENSED - Copyright (c) 2025 Bernier LLC