# Node.js Quickstart Generator

[![npm version](https://img.shields.io/npm/v/nodejs-quickstart-structure.svg?style=flat-square)](https://www.npmjs.com/package/nodejs-quickstart-structure)
![Total Clones](https://img.shields.io/badge/dynamic/json?color=brightgreen&label=total%20clones&query=total_clones&url=https%3A%2F%2Fraw.githubusercontent.com%2Fpaudang%2Fnodejs-quickstart-structure%2Foutput%2Ftotal_stats.json&style=flat-square)
[![npm total downloads](https://img.shields.io/npm/dt/nodejs-quickstart-structure?style=flat-square&color=emerald&label=Downloads)](https://www.npmjs.com/package/nodejs-quickstart-structure)
[![npm monthly downloads](https://img.shields.io/npm/dm/nodejs-quickstart-structure.svg?style=flat-square)](https://www.npmjs.com/package/nodejs-quickstart-structure)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://opensource.org/licenses/ISC)


---

A powerful ecosystem to scaffold production-ready Node.js microservices with built-in best practices. Choose between **MVC** or **Clean Architecture**, **JavaScript** or **TypeScript**, and your preferred tech stack in seconds.

## Table of Contents

- [Quick Start](#choose-your-journey)
- [What's New](#whats-new-in-v25-the-cloud--observability-release)
- [Key Features](#key-features)
- [Professional Standards](#professional-standards)
- [2.69M Project Combinations](#269m-project-combinations)
- [Configuration Options](#configuration-options)
- [Generated Project Structure](#generated-project-structure)
- [Documentation](#documentation)
- [Support & Roadmap](#support--roadmap)

## Choose Your Journey
 
| **Path A: Next-Gen Web UI** (Recommended) | **Path B: Interactive CLI** |
| :--- | :--- |
| <a href="https://nodejs-quickstart-generator.netlify.app/#configurator"><img src="docs/public/v2-preview.png" width="100%" alt="UI Preview"></a> | <img src="docs/demo.gif" width="100%" alt="CLI Demo"> |
| [Try Visual Configurator →](https://nodejs-quickstart-generator.netlify.app/#configurator) | [See CLI Commands ↓](#path-b-interactive-cli) |
| **Visual Preview**: Real-time folder simulation. | **Fast & Direct**: Quickly scaffold in terminal. |
| **Zero-Prompt**: Paste a tailored command. | **AI-Ready**: Generates `.cursorrules`. |

---

### Path B: Interactive CLI
**Scaffold your project directly from your terminal in seconds.**

Run the generator using your preferred package manager (no global installation required):

```bash
# npm
npx nodejs-quickstart-structure@latest init

# pnpm
pnpm dlx nodejs-quickstart-structure@latest init

# yarn
yarn dlx nodejs-quickstart-structure@latest init
```

*Or install globally:*
```bash
# npm
npm install -g nodejs-quickstart-structure

# pnpm
pnpm add -g nodejs-quickstart-structure

# yarn
yarn global add nodejs-quickstart-structure

# Then run:
nodejs-quickstart init
```

---

## What's New in v2.9 (The API Gateway Release)

The v2.9.0 release brings enterprise-grade edge routing and intelligent natural language processing to your architecture:

- **API Gateway Integration**: Spin up production-ready **Nginx** (Rate Limiting, Security Headers) or **Kong DB-less** (Key-Auth Plugin) seamlessly in front of your Node.js application.
- **AI/NLP Prompting Engine**: Upgraded heuristic parsing handles complex, multi-lingual, and double-negative prompts flawlessly (e.g., "bỏ qua Gateway", "不要网关").
- **Gamification Mechanics Updated**: The "Backend Factorio Builder" now computes true rate limits, rewarding players who implement API Gateways to survive `1000 Req/s` loads.
- **Massive Matrix Expansion**: The total architectural combinations possible have expanded from 1.41 Million to **2.69 Million** robust blueprints!

---

## What's New in v2.8 (The Generator Multiverse Release)

The v2.8.0 release introduces a revolutionary Gamification layer to the scaffolding experience:

- **The Architecture Skill Tree**: An RPG-style interactive tech tree designed to help developers systematically build an enterprise application from the ground up.
- **Backend Factorio Builder**: A drag-and-drop puzzle mode where users connect nodes to construct production-ready microservice pipelines.
- **Dynamic 100% Feature Parity**: The interactive games map 1:1 with the CLI, seamlessly generating complex setups like Multi-Cloud Terraform, CI/CD, Authentication, and ELK Stack.
- **Zero-Vulnerability Baseline**: Strictly enforced package overrides to guarantee pristine `snyk test` and `npm audit` reports out-of-the-box.

---

## Key Features

- **Interactive CLI**: Smooth, guided configuration process.
- **Multiple Architectures**: Supports both **MVC** and **Clean Architecture**.
- **Modern Languages**: Choice of **JavaScript** or **TypeScript**.
- **Database Ready**: Pre-configured for **MySQL**, **PostgreSQL**, or **MongoDB**.
- **Communication Patterns**: Supports **REST**, **GraphQL** (Apollo), and **Kafka** (Event-driven).
- **Multi-layer Caching**: Integrated **Redis** or built-in **Memory Cache**.
- **Pluggable Authentication**: Built-in **JWT** and **OAuth2 (Google/GitHub)** support with Access/Refresh token rotation.
- **AI-Native Optimized**: specifically designed for **Cursor** and AI agents, including built-in `.cursorrules` and Agent Skill prompts.

---

## Professional Standards

We don't just generate boilerplate; we generate **production-ready** foundations. Every project includes:

- **Code Quality**: Pre-configured `Eslint` and `Prettier`.
- **Enterprise Security**: Integrated **Snyk (SCA)**, **SonarCloud (SAST)**, `Helmet`, `HPP`, and Rate-Limiting.
- **Robust Error Handling**: Centralized global error middleware with custom error classes (`ApiError`, `NotFoundError`, etc.) — consistent across REST & GraphQL.
- **Testing Excellence**: Integrated `Jest` and `Supertest` with **>80% Unit Test coverage** out of the box.
- **DevOps & CI/CD**: Optimized **Multi-Stage Dockerfiles**, health checks, infrastructure retry logic, and workflows for **GitHub Actions**, **Jenkins**, **GitLab CI**, **CircleCI**, and **Bitbucket Pipelines**.
- **Scalable Deployment**: Integrated **PM2 Ecosystem** config for zero-downtime reloads.

---

## 2.69M+ Project Combinations

The CLI provides massive flexibility to fit your exact needs. Instead of a rigid boilerplate, it acts like architectural Lego blocks. 

- **1,419,264+ Verified Scenarios**: Whether you choose `MongoDB + GraphQL + Redis` or `PostgreSQL + REST + No Cache`, the generated code compiles, runs, and passes tests out-of-the-box.
- **Mix & Match**: Seamlessly combine your preferred Database, Caching, Auth, and Communication patterns.
- **Enterprise-Ready**: Every combination guarantees compatibility with our **80% Test Coverage** policy, Docker builds, and CI/CD pipelines.

> Curious about the math? Check out our [Mathematical Verification Matrix](docs/generateCase.md) for the full calculation.

---

## Configuration Options

The CLI will guide you through:
1. **Project Name**
2. **Language**: `JavaScript` | `TypeScript`
3. **Architecture**: `MVC` | `Clean Architecture`
4. **View Engine**: (MVC only) `None` | `EJS` | `Pug`
5. **Communication**: `REST` | `GraphQL` | `Kafka`
6. **Database**: `MySQL` | `PostgreSQL` | `MongoDB`
7. **Caching**: `None` | `Redis` | `Memory Cache`
8. **Auth**: `None` | `JWT` | `OAuth2 (Google/GitHub) + JWT`
9. **CI/CD**: `GitHub Actions` | `Jenkins` | `GitLab CI` | `CircleCI` | `Bitbucket Pipelines`
10. **Security**: (Optional) Snyk & SonarCloud Hardening
11. **Advanced Options**: `Yes` | `No`
    - **Resilience**: (Optional) `Timeout` | `Retry` | `Circuit Breaker`
    - **Cloud Infrastructure**: (Optional IaC) Terraform for `AWS` | `GCP` | `Azure` (`None` | `Standard` | `Production`)
    - **Observability**: (Optional) Centralized Logging via `ELK Stack`
    - **Background Jobs**: (Optional) `BullMQ` + `Bull-Board` Task Queues (Requires Redis)
    - **API Gateway**: (Optional) `Nginx` | `Kong DB-less`

---

## Generated Project Structure
Depending on your choices, the structure adapts. Here is a **TypeScript + Clean Architecture** preview:

```text
.
├── src/
│   ├── application/     # Use cases & Business logic
│   ├── domain/          # Entities & Repository interfaces
│   ├── infrastructure/  # DB, External services, Repositories
│   ├── interfaces/      # Controllers, Routes, GraphQL, Kafka
│   ├── errors/          # Custom Error Classes
│   ├── config/          # Environment & Global settings
│   └── index.ts         # Server entry point
├── flyway/sql/          # SQL migrations (if applicable)
├── docker-compose.yml   # Infrastructure services
├── package.json         # Scripts and dependencies
├── .cursorrules         # AI assistance rules (The "AI Brain")
└── .env.example         # Environment template
```

---

## Documentation

For full guides, architecture deep-dives, and feature references, visit our **[Official Documentation Site](https://nodejs-quickstart-generator.netlify.app/guide/getting-started.html)**.

---

## Support & Roadmap

### Support the Project
If this tool helped you build your project faster, please support us:
- Give us a ⭐ on [GitHub](https://github.com/paudang/nodejs-quickstart-structure) to help us reach our next milestone!
- Read our [Medium Series](https://medium.com/@paudang/nodejs-quickstart-generator-93c276d60e0b) for architecture deep-dives.

### Roadmap
Track our progress and vote for features on our public board:
**[View our Public Roadmap on Trello](https://trello.com/b/TPTo8ylF/nodejs-quickstart-structure-product)**

---

If this tool saved you hours of work, **[please give us a Star!](https://github.com/paudang/nodejs-quickstart-structure)**

---

## License

ISC
