npm package: @nestgate/setup
Description: One-line NestJS application setup with Swagger, Redoc, validation, and CORS
Author: berkerozer
Latest version: 0.0.1

# @nestgate/setup

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

## 📦 Installation

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

### Peer Dependencies

```bash
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

### Disable Redoc (Swagger Only)

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

### Disable Swagger (Redoc Only)

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

### Custom Validation Rules

```typescript
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

```typescript
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()`:

```typescript
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

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

### Custom Redoc Theme

```typescript
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) - Core utilities and decorators
- [@nestgate/rest](../rest) - REST API decorators
- [@nestgate/entity](../entity) - Entity validation decorators

## 📝 License

MIT © [NestGate](https://nestgate.org)

## 🤝 Contributing

Contributions are welcome! Please see our [Contributing Guide](../../CONTRIBUTING.md).

## 💬 Support

- [Documentation](https://nestgate.org)
- [GitHub Issues](https://github.com/nestgate/nestgate/issues)
- [Discord](https://discord.gg/nestgate)