npm package: @newagesmb/api-cli
Description: Nest Core CLI for NewAgeSys Inc.
Author: Jasif Shameem K
Latest version: 2.2.2

<h1 align="center">
  @newagesmb/api-cli
</h1>

<p align="center">
  Interactive CLI to create and manage enterprise-grade NestJS applications.
</p>

<p align="center">
  Get started with the SMB Nest App by running <code>npx @newagesmb/api-cli new app-name</code>
</p>

## Table of Contents

- [🚀 Getting Started](#getting-started)
- [✨ Features](#features)
- [📦 Available Packages](#available-packages)
- [🛠️ Commands](#commands)
- [🏗️ Architecture](#architecture)
- [📖 Examples](#examples)
- [🔧 Development](#development)

## 🚀 Getting Started

To scaffold an app using `@newagesmb/api-cli`, run any of the following commands:

### npm

```bash
npm i -g @newagesmb/api-cli
nac new my-awesome-app
```

### yarn

```bash
yarn global add @newagesmb/api-cli
nac new my-awesome-app
```

### pnpm

```bash
pnpm add -g @newagesmb/api-cli
nac new my-awesome-app
```

## ✨ Features

- **🎯 GitHub-Based Architecture**: Always uses the latest core template from the repository
- **🗄️ Database Support**: Choose between MongoDB and SQL (MySQL/PostgreSQL)
- **📦 Modular Packages**: Add third-party integrations like Firebase, Stripe, Twilio
- **🚀 Smart Caching**: Templates are cached locally for faster project creation
- **🔧 Module Generation**: Generate CRUD modules with a single command
- **➕ Add Packages**: Add new packages to existing projects seamlessly
- **🏷️ TypeScript First**: Full TypeScript support with strict type checking
- **🧪 Testing Ready**: Comes with Jest setup for unit and e2e tests
- **📚 Production Ready**: PM2 configuration, environment setup, and more

## 📦 Available Packages

| Package | Description | Use Case |
|---------|-------------|----------|
| **email** | Email service with templates | Transactional emails, notifications |
| **firebase** | Firebase Admin SDK | Authentication, push notifications |
| **stripe** | Stripe payment processing | Payments, subscriptions |
| **square** | Square payment processing | In-person and online payments |
| **twilio** | SMS and communication | SMS notifications, voice calls |
| **geocoder** | Location services | Address geocoding, maps |
| **recaptcha** | Bot protection | Form validation, security |

## 🛠️ Commands

### Create New Project

```bash
# Interactive mode (recommended)
nac new my-app

# With specific database
nac new my-app --mongo
nac new my-app --sql --mysql
nac new my-app --sql --postgresql

# Skip package selection
nac new my-app --noPackages

# Skip git initialization
nac new my-app --noGit

# Skip dependency installation
nac new my-app --noInstall
```

### Add Packages to Existing Project

```bash
# Add a single package
nac add stripe

# Add without installing dependencies
nac add firebase --noInstall
```

### Generate Modules

```bash
# Generate a new CRUD module
nac module user-profile

# Generate without test files
nac module payment --noSpec

# Force specific database engine
nac module order --useMongo
nac module invoice --useSql
```

### Cache Management

```bash
# Show cache information
nac cache --info

# Clear template cache
nac cache --clear
```

## 🏗️ Architecture

### GitHub-Based Templates

The CLI uses a revolutionary **GitHub-based architecture** that eliminates template duplication:

- **Single Source of Truth**: All templates come from the core repository
- **Always Up-to-Date**: Automatically gets the latest features and fixes
- **Smart Caching**: Templates are cached locally for performance
- **Zero Maintenance**: No need to maintain separate template copies

### Template Modification Engine

The CLI includes a sophisticated template modification system:

- **Selective Packaging**: Only includes selected modules and dependencies
- **Database Engine Selection**: Removes unused database modules
- **Import Management**: Automatically manages TypeScript imports
- **Configuration Updates**: Updates package.json, tsconfig, and environment files

### Project Structure

Generated projects follow a modular architecture:

```
my-app/
├── libs/                    # Shared library modules
│   ├── mongo/              # MongoDB integration
│   ├── email/              # Email service
│   └── stripe/             # Payment processing
├── src/
│   ├── core/               # Core utilities and decorators
│   ├── config/             # Configuration files
│   ├── modules/            # Feature modules
│   │   ├── mongo/          # MongoDB-specific modules
│   │   └── sql/            # SQL-specific modules
│   └── main.ts
├── test/                   # E2E tests
├── .nac-metadata.json      # CLI metadata
└── package.json
```

## 📖 Examples

### Full-Stack E-commerce App

```bash
nac new ecommerce-api --sql --mysql
cd ecommerce-api
nac add stripe
nac add email
nac module product
nac module order
nac module customer
```

### Real-time Chat Application

```bash
nac new chat-api --mongo
cd chat-api
nac add firebase
nac add twilio
nac module chat-room
nac module message
nac module user-presence
```

### Location-based Service

```bash
nac new location-api --postgresql
cd location-api
nac add geocoder
nac add recaptcha
nac module location
nac module search
```

## 🔧 Development

### Building the CLI

```bash
# Install dependencies
npm install

# Type checking
npm run typecheck

# Build
npm run build

# Development mode
npm run dev
```

### Testing

```bash
# Run type checking
npm run typecheck

# Build and test
npm run build
node dist/index.js new test-app

cd test-app
node ../dist/index.js m
```

### Local Development

For local development, the CLI can use a local core repository:

1. Clone the core repository
2. Update `src/core/repository.ts` with the local path
3. Set `cache: false` for immediate changes

---

<p align="center">
  Built with ❤️ by <a href="https://newagesmb.com">NewAgeSys Inc.</a>
</p>