@nestgate/setup

Quick and elegant NestJS application setup with Swagger, Redoc, validation, and more - all in one line.

📦 Installation

npm install @nestgate/setup
# or
pnpm add @nestgate/setup
# or
yarn add @nestgate/setup

Peer Dependencies

npm install @nestjs/common @nestjs/swagger nestjs-redoc class-validator class-transformer

🎯 Features

• 🚀 One-line setup - Configure your entire app with minimal code
• 📚 Swagger UI - Auto-generated API documentation
• 📖 Redoc - Beautiful alternative documentation
• ✅ Global Validation - Automatic request validation
• 🌐 CORS - Enable cross-origin requests
• 🔧 Sensible Defaults - Works out of the box

🚀 Quick Start

Minimal Setup

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { setup } from '@nestgate/setup';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  await setup(app, {
    title: 'My API',
    port: 3000,
  });
}

bootstrap();

That's it! Your app now has:

• ✅ Swagger UI at http://localhost:3000/api
• ✅ Redoc at http://localhost:3000/docs
• ✅ Global validation enabled
• ✅ CORS enabled

📚 API Reference

setup(app, options)

Configure your NestJS application with all the bells and whistles.

Parameters

• app - NestJS application instance
• options - Configuration options

Options

interface SetupOptions {
  // Basic info (required)
  title: string;
  description?: string;
  version?: string;

  // Server config
  globalPrefix?: string; // e.g., 'api/v1'
  port?: number; // Auto-listen on this port
  cors?: boolean; // Default: true

  // Swagger config
  swagger?: {
    enabled?: boolean; // Default: true
    path?: string; // Default: 'api'
    jsonPath?: string; // Default: 'api/openapi.json'
    customCss?: string; // Custom CSS for Swagger UI
  };

  // Redoc config
  redoc?: {
    enabled?: boolean; // Default: true
    path?: string; // Default: 'docs'
    logo?: {
      url: string;
      backgroundColor?: string;
      altText?: string;
    };
    auth?: {
      enabled: boolean;
      user: string;
      password: string;
    };
    theme?: any; // Redoc theme customization
  };

  // Validation config
  validation?: {
    enabled?: boolean; // Default: true
    whitelist?: boolean; // Default: true
    forbidNonWhitelisted?: boolean; // Default: true
    transform?: boolean; // Default: true
  };
}

💡 Examples

Basic Setup

await setup(app, {
  title: 'My API',
  description: 'API for my awesome app',
  version: '1.0.0',
  port: 3000,
});

// Output:
// 🚀 Application is running on: http://localhost:3000
// 📚 Swagger UI: http://localhost:3000/api
// 📖 Redoc UI: http://localhost:3000/docs

Custom Paths

await setup(app, {
  title: 'My API',
  globalPrefix: 'api/v2',
  swagger: {
    path: 'swagger',
    jsonPath: 'swagger/openapi.json',
  },
  redoc: {
    path: 'documentation',
  },
  port: 4000,
});

// Swagger: http://localhost:4000/swagger
// Redoc: http://localhost:4000/documentation
// All endpoints: http://localhost:4000/api/v2/...

With Custom Logo and Theme

await setup(app, {
  title: 'Company API',
  redoc: {
    logo: {
      url: 'https://company.com/logo.png',
      backgroundColor: '#FFFFFF',
      altText: 'Company Logo',
    },
    theme: {
      colors: {
        primary: {
          main: '#FF6B6B',
        },
      },
      menu: {
        width: '350px',
      },
    },
  },
  port: 3000,
});

Protected Documentation

await setup(app, {
  title: 'Internal API',
  redoc: {
    auth: {
      enabled: true,
      user: 'admin',
      password: 'supersecret',
    },
  },
  port: 3000,
});

Disable Redoc (Swagger Only)

await setup(app, {
  title: 'Simple API',
  redoc: {
    enabled: false,
  },
  port: 3000,
});

Disable Swagger (Redoc Only)

await setup(app, {
  title: 'Documentation API',
  swagger: {
    enabled: false,
  },
  port: 3000,
});

Custom Validation Rules

await setup(app, {
  title: 'Strict API',
  validation: {
    enabled: true,
    whitelist: true, // Strip unknown properties
    forbidNonWhitelisted: true, // Throw error on unknown properties
    transform: true, // Auto-transform types
  },
  port: 3000,
});

Production Setup

await setup(app, {
  title: 'Production API',
  description: 'Production-ready API',
  version: '2.0.0',
  globalPrefix: 'api',
  cors: true,
  swagger: {
    enabled: process.env.NODE_ENV !== 'production', // Disable in prod
  },
  redoc: {
    enabled: true,
    auth: {
      enabled: true,
      user: process.env.DOCS_USER,
      password: process.env.DOCS_PASSWORD,
    },
  },
  validation: {
    enabled: true,
    whitelist: true,
    forbidNonWhitelisted: true,
  },
  port: parseInt(process.env.PORT) || 3000,
});

Without Auto-listen

If you want to manually call app.listen():

await setup(app, {
  title: 'My API',
  // Don't provide port
});

// Listen manually
await app.listen(3000);
console.log('Server started on port 3000');

🎨 Customization

Custom Swagger CSS

await setup(app, {
  title: 'Styled API',
  swagger: {
    customCss: `
      .swagger-ui .topbar { display: none }
      .swagger-ui .info .title { color: #FF6B6B; }
    `,
  },
  port: 3000,
});

Custom Redoc Theme

await setup(app, {
  title: 'Themed API',
  redoc: {
    theme: {
      colors: {
        primary: {
          main: '#3B82F6',
        },
        success: {
          main: '#10B981',
        },
        error: {
          main: '#EF4444',
        },
      },
      typography: {
        fontSize: '14px',
        fontFamily: 'Inter, sans-serif',
      },
      menu: {
        width: '300px',
        backgroundColor: '#F9FAFB',
      },
    },
  },
  port: 3000,
});

🔗 Related Packages

• @nestgate/core - Core utilities and decorators
• @nestgate/rest - REST API decorators
• @nestgate/entity - Entity validation decorators

📝 License

MIT © NestGate

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

💬 Support

• Documentation
• GitHub Issues
• Discord