npm package: @nodelabs/nest-app
Description: CLI to scaffold a production-ready NestJS application
Author: nodelabs
Latest version: 1.0.1

# @nodelabs/nest-app

A powerful CLI tool to scaffold production-ready NestJS applications with customizable database support, AWS integrations, and modular architecture.

![npm version](https://img.shields.io/npm/v/@nodelabs/nest-app)
![license](https://img.shields.io/npm/l/@nodelabs/nest-app)
![downloads](https://img.shields.io/npm/dm/@nodelabs/nest-app)

## ✨ Features

- **Fast scaffolding** of production-ready NestJS applications
- **Multiple database support** (PostgreSQL, MySQL, MongoDB)
- **AWS integrations** (S3, SES, Cognito) with zero configuration
- **Modular package system** for adding features to existing projects
- **Pre-configured** with TypeScript, ESLint, and Docker
- **Built-in authentication** with JWT and role-based access control
- **Email service** integration ready
- **Pagination utilities** and common DTOs
- **Testing setup** with Jest for e2e tests

## Quick Start

### Installation

```bash
# Install globally
npm install -g @nodelabs/nest-app

# Or use npx (recommended)
npx @nodelabs/nest-app create my-app
```

### Create a New Project

```bash
npx @nodelabs/nest-app create my-awesome-app
```

This will start an interactive setup process where you can configure:

- **Database**: PostgreSQL, MySQL, or MongoDB
- **AWS S3**: For file uploads with presigned URLs
- **AWS SES**: For transactional email sending
- **AWS Cognito**: For user authentication and authorization

### Project Structure

The generated project follows a clean, modular architecture:

```
my-awesome-app/
├── src/
│   ├── main.ts                 # Application entry point
│   ├── main.module.ts          # Root module
│   ├── app/
│   │   ├── app.controller.ts   # Health check endpoint
│   │   ├── app.module.ts       # Core app module
│   │   ├── auth/               # Authentication module
│   │   └── uploads/            # File upload module (if S3 enabled)
│   ├── config/
│   │   ├── configuration.module.ts
│   │   ├── read-config.util.ts
│   │   └── database/
│   │       └── datasource.ts   # Database configuration
│   └── libs/
│       ├── auth/               # Reusable auth library
│       ├── common/             # Common DTOs and interfaces
│       ├── mailer/             # Email service library
│       ├── users/              # User management library
│       └── utils/              # Utility functions
├── test/                       # E2E tests
├── docker/                     # Docker configurations
├── .env.example               # Environment variables template
├── tsconfig.json              # TypeScript configuration
├── nest-cli.json              # NestJS CLI configuration
└── package.json
```

## Package Management

Add optional packages to existing projects using the built-in package manager:

### List Available Packages

```bash
npx @nodelabs/nest-app package list
```

### Add AWS S3 Support

```bash
cd your-existing-project
npx @nodelabs/nest-app package add aws-s3
```

This adds:
- File upload controller with presigned URL generation
- S3 module configuration
- Upload DTOs and interfaces
- Required AWS SDK dependencies

### Add AWS SES Support

```bash
npx @nodelabs/nest-app package add aws-ses
```

This adds:
- SES module for transactional emails
- Enhanced mailer service with SES integration
- Email template support
- Required AWS SDK dependencies

## Configuration

### Environment Variables

The generated project includes comprehensive environment configuration:

```env
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=user
DB_PASSWORD=password
DB_NAME=myapp

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=7d

# AWS Configuration (if using AWS services)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

# AWS S3 (if enabled)
AWS_S3_BUCKET=your-bucket-name

# AWS SES (if enabled)
AWS_SES_DEFAULT_SENDER=no-reply@yourdomain.com

# Application
APP_NAME=MyApp
APP_VERSION=1.0.0
NODE_ENV=development
PORT=3000
```

### Database Support

Choose from three popular databases during setup:

- **PostgreSQL** (recommended for most applications)
- **MySQL** (great for traditional web applications)  
- **MongoDB** (perfect for document-based data)

The generated project includes:
- TypeORM configuration for relational databases
- Mongoose configuration for MongoDB
- Database connection utilities
- Environment-based configuration

## Built-in Features

### Authentication & Authorization

- **JWT-based authentication** with refresh tokens
- **Role-based access control** (RBAC)
- **Guard decorators** for protecting routes
- **User registration and login** endpoints
- **Password reset** functionality
- **Current user decorator** for easy user context access

### File Uploads (with AWS S3)

- **Presigned URL generation** for secure direct uploads
- **File metadata tracking** 
- **Upload validation** and size limits
- **Organized file storage** with configurable paths

### Email Service

- **Template-based emails** with Handlebars
- **Multiple email providers** support (SES, SMTP)
- **Queue integration** ready for background processing
- **Email validation** and formatting utilities

### Common Utilities

- **Pagination helpers** with metadata
- **Date utilities** for consistent date handling
- **Password utilities** with bcrypt hashing
- **Response formatting** utilities
- **Error handling** middleware

## Docker Support

Every project comes with production-ready Docker configurations:

```bash
# Development
docker build -f docker/Dockerfile.dev -t my-app:dev .

# Production
docker build -f docker/Dockerfile.prod -t my-app:prod .
```

## Testing

The generated project includes a complete testing setup:

```bash
# Run unit tests
npm run test

# Run e2e tests
npm run test:e2e

# Run tests with coverage
npm run test:cov
```

## Available Commands

| Command | Description |
|---------|-------------|
| `create <name>` | Create a new NestJS application |
| `package list` | List all available optional packages |
| `package add <name>` | Add an optional package to existing project |


Made with ❤️ by [Abiral](https://abrlnp.me)