|
1 | 1 | <div align="center"> |
2 | | - <h1>🚀 Node Module Generator</h1> |
3 | | - <p>A robust CLI tool for scaffolding Express.js projects using Clean Architecture & Dependency Injection.</p> |
| 2 | + <img src="https://raw.githubusercontent.com/saul-paulus/node-module-generator/main/assets/banner.png" alt="Node Module Generator Banner" width="600" style="max-width: 100%;" /> |
| 3 | + <h1>🚀 Node Module Generator (NMG)</h1> |
| 4 | + <p><strong>The ultimate CLI companion for rapid, enterprise-grade Node.js scaffolding.</strong></p> |
4 | 5 | <p> |
5 | 6 | <a href="https://github.com/saul-paulus/node-module-generator/actions/workflows/ci.yml"> |
6 | 7 | <img src="https://github.com/saul-paulus/node-module-generator/actions/workflows/ci.yml/badge.svg" alt="CI Status"> |
7 | 8 | </a> |
8 | 9 | <a href="https://www.npmjs.com/package/@saulpaulus17/node-module-generator"> |
9 | | - <img src="https://img.shields.io/npm/v/@saulpaulus17/node-module-generator.svg" alt="NPM Version" /> |
| 10 | + <img src="https://img.shields.io/npm/v/@saulpaulus17/node-module-generator.svg?logo=npm&logoColor=white" alt="NPM Version" /> |
10 | 11 | </a> |
11 | 12 | <a href="https://www.npmjs.com/package/@saulpaulus17/node-module-generator"> |
12 | | - <img src="https://img.shields.io/npm/dt/@saulpaulus17/node-module-generator.svg" alt="NPM Downloads" /> |
| 13 | + <img src="https://img.shields.io/npm/dt/@saulpaulus17/node-module-generator.svg?logo=npm&logoColor=white" alt="NPM Downloads" /> |
13 | 14 | </a> |
14 | 15 | <a href="https://github.com/saul-paulus/node-module-generator/blob/main/LICENSE"> |
15 | 16 | <img src="https://img.shields.io/npm/l/@saulpaulus17/node-module-generator.svg" alt="License" /> |
|
19 | 20 |
|
20 | 21 | --- |
21 | 22 |
|
22 | | -## 📖 Overview |
| 23 | +## 🏛️ Architecture Overview |
| 24 | + |
| 25 | +Node Module Generator (NMG) enforces **Clean Architecture** principles to ensure your backend remains scalable, testable, and decoupled. It is purpose-built for high-performance **Express.js** environments using **Awilix** for Dependency Injection. |
| 26 | + |
| 27 | +### Layered Structure |
| 28 | +```mermaid |
| 29 | +graph TD |
| 30 | + UI[Interfaces Layer: Controllers & Routes] --> APP[Application Layer: Use Cases & DTOs] |
| 31 | + APP --> DOM[Domain Layer: Entities & Repository Interfaces] |
| 32 | + INF[Infrastructure Layer: Repository Impl & External Services] --> DOM |
| 33 | + |
| 34 | + subgraph "Inner Layers" |
| 35 | + DOM |
| 36 | + APP |
| 37 | + end |
| 38 | + |
| 39 | + subgraph "Outer Layers" |
| 40 | + UI |
| 41 | + INF |
| 42 | + end |
| 43 | +``` |
23 | 44 |
|
24 | | -**Node Module Generator** provides a world-class Developer Experience (DX) equivalent to the robust CLIs found in ecosystems like NestJS or Angular, but designed specifically for pure Node.js environments utilizing **Express.js** and **Clean Architecture**. |
| 45 | +--- |
25 | 46 |
|
26 | | -It instantly scaffolds fully-tested, decoupled, and highly cohesive module structures with built-in Dependency Injection using **Awilix**. |
| 47 | +## 🔥 Key Features |
27 | 48 |
|
28 | | -## ✨ Features |
| 49 | +- 💎 **Clean Architecture by Design**: Strict separation into Domain, Application, Infrastructure, and Interface layers. |
| 50 | +- 💉 **Native Dependency Injection**: Fully pre-configured for **Awilix**, providing seamless DI management. |
| 51 | +- 🧪 **Test-Ready Scaffolding**: Automatically generates **Jest** test suites for Controllers and Use Cases. |
| 52 | +- 🚀 **Modern Tooling**: Native support for **ES Modules (ESM)**, **Prisma ORM**, and **Joi/Zod** DTO patterns. |
| 53 | +- 🤖 **Granular Control**: Generate full modules or individual components (UseCases, Repos, DTOs) without disrupting existing code. |
29 | 54 |
|
30 | | -- 🏗️ **Clean Architecture by Default**: Automatically separates concerns into Domain, Application, Infrastructure, and Interface layers. |
31 | | -- 💉 **Dependency Injection Ready**: Auto-generates Awilix configurations mapped correctly across use cases, controllers, and repositories. |
32 | | -- 🧪 **Test-Driven Design**: Scaffolds adjoining `*.test.js` files containing boilerplates for Jest to promote TDD. |
33 | | -- 🤖 **Continuous Integration**: Codebase natively incorporates GitHub Actions for automated unit testing checks. |
34 | | -- 🧩 **Granular Scaffolding**: Generate specific components (UseCases, Repositories, DTOs) dynamically on demand without overriding existing folders! |
| 55 | +--- |
35 | 56 |
|
36 | 57 | ## 📦 Installation |
37 | 58 |
|
38 | 59 | ### Prerequisites |
39 | | -- **Node.js**: v18.0.0 or higher. |
40 | | -- **NPM** or **Yarn**. |
| 60 | +- **Node.js**: v18.0.0 or higher (LTS recommended) |
| 61 | +- **NPM**, **Yarn**, or **PNPM** |
41 | 62 |
|
42 | | -To use this CLI tool locally or globally on your machine, you can install it directly from NPM. |
| 63 | +### Global Installation (Recommended) |
| 64 | +Install NMG globally to access the command from any project. |
43 | 65 |
|
44 | 66 | ```bash |
45 | | -# Install globally via NPM |
46 | 67 | npm install -g @saulpaulus17/node-module-generator |
47 | 68 | ``` |
48 | 69 |
|
49 | | -## 🚀 Usage |
| 70 | +### Direct Execution |
| 71 | +Run it on-the-fly without a permanent installation: |
50 | 72 |
|
51 | | -Once installed globally, you can execute the CLI commands from any of your Node.js project directories using the `nmg` command keyword. |
| 73 | +```bash |
| 74 | +npx @saulpaulus17/node-module-generator <command> <name> |
| 75 | +``` |
52 | 76 |
|
53 | | -### Granular CLI Commands |
54 | | -Scaffold specifically what you need, exactly how you do it in NestJS: |
| 77 | +--- |
55 | 78 |
|
56 | | -```bash |
57 | | -# 1. Scaffolds a new module architecture and empty DI registry |
58 | | -nmg module product |
| 79 | +## 🚀 Detailed Usage |
59 | 80 |
|
| 81 | +### 1. Generating a Full Module |
| 82 | +Scaffolds a complete standard architecture with all 4 layers and initial unit tests. |
60 | 83 |
|
61 | | -# 2. Creates a specific Use Case and its Test inside an existing module |
62 | | -nmg usecase updateProduct --module=product |
| 84 | +```bash |
| 85 | +nmg module Auth |
| 86 | +``` |
63 | 87 |
|
64 | | -# 3. Creates Domain Entity and Repository Interfaces/Implementations |
65 | | -nmg repository product |
| 88 | +### 2. Generating Individual Components |
| 89 | +Quickly add specific components to an existing module structure. |
| 90 | + |
| 91 | +```bash |
| 92 | +# Add a new UseCase (e.g., login) to the Auth module |
| 93 | +nmg usecase login --module=Auth |
66 | 94 |
|
67 | | -# 4. Scaffolds a DTO validation schema |
68 | | -nmg dto getProduct --module=product |
| 95 | +# Add a Repository Interface and Implementation (Prisma) |
| 96 | +nmg repository User |
69 | 97 |
|
70 | | -# 5. Generates an entire full-stack CRUD Resource (Controller, Entity, Repos, DI, etc.) |
71 | | -nmg resource order |
| 98 | +# Add a DTO validation schema |
| 99 | +nmg dto userRegistration --module=Auth |
72 | 100 | ``` |
73 | 101 |
|
74 | | -_(Note: If you haven't installed the package globally, you can run it via `npx @saulpaulus17/node-module-generator <command> <name>`)_ |
| 102 | +--- |
75 | 103 |
|
76 | | -## 📂 Full Resource Structure |
| 104 | +## 📂 Project Blueprint |
77 | 105 |
|
78 | | -Running the powerhouse command `nmg resource user` instantly generates the following decoupled blueprint within your project's `src/modules` directory: |
| 106 | +Scaffolding a module (e.g., `nmg module Product`) produces the following industry-standard structure: |
79 | 107 |
|
80 | 108 | ```text |
81 | | -src/modules/user/ |
82 | | -├── application/ # Orchestration & Use Cases |
83 | | -│ ├── dtos/ # (Generated schema references) |
84 | | -│ └── usecases/ |
85 | | -│ ├── create-user.usecase.js # Business logically perfectly isolated |
86 | | -│ └── create-user.usecase.test.js # Scaffolded test harness |
87 | | -├── domain/ # Blueprints & Business Rules (Pure Logic) |
88 | | -│ ├── entities/ |
89 | | -│ │ └── user.entity.js |
90 | | -│ └── repositories/ # Repository Interfaces (Contracts) |
91 | | -│ └── user.repository.interface.js |
92 | | -├── infrastructure/ # Technical Details & Implementation |
93 | | -│ ├── repositories/ # Implementations (mocked to replace with Prisma/TypeORM) |
94 | | -│ │ └── user.repository.impl.js |
95 | | -│ └── validation/ # Input validation schemas |
96 | | -│ └── create-user.schema.js # Auto-stubbed validation schema |
97 | | -├── interfaces/ # Entry Points (Web/API) |
98 | | -│ ├── controllers/ |
99 | | -│ │ ├── user.controller.js # Express.js class handlers |
100 | | -│ │ └── user.controller.test.js |
101 | | -│ └── routes/ |
102 | | -│ └── user.routes.js # Express routers integrating the controller |
103 | | -└── user.module.js # Centralised Awilix Dependency Injection bindings |
| 109 | +src/modules/Product/ |
| 110 | +├── application/ |
| 111 | +│ ├── dtos/ # DTO schemas (e.g., product.dto.js) |
| 112 | +│ └── usecases/ # Business orchestration |
| 113 | +│ ├── ProductUseCase.js # Logic implementation |
| 114 | +│ └── ProductUseCase.test.js # Unit tests |
| 115 | +├── domain/ |
| 116 | +│ ├── entities/ # Business entity definitions |
| 117 | +│ │ └── Product.js |
| 118 | +│ └── repositories/ # Repository Interface (Contracts) |
| 119 | +│ └── ProductRepository.js |
| 120 | +├── infrastructure/ |
| 121 | +│ ├── repositories/ # Implementation (default: Prisma) |
| 122 | +│ │ └── PrismaProductRepository.js |
| 123 | +├── interfaces/ |
| 124 | +│ ├── controllers/ # Express handlers |
| 125 | +│ │ ├── ProductController.js |
| 126 | +│ │ └── ProductController.test.js |
| 127 | +│ └── routes/ # Express routes & method binding |
| 128 | +│ └── product.routes.js |
| 129 | +└── Product.module.js # Central Awilix Module Registration |
104 | 130 | ``` |
105 | 131 |
|
106 | | -## 🛠️ Technological Footprint |
| 132 | +--- |
| 133 | + |
| 134 | +## 🛠️ Post-Scaffolding Integration |
107 | 135 |
|
108 | | -The scaffolded code integrates perfectly if you are using the following libraries in your Express application: |
| 136 | +To finalize your new module integration, follow these standard steps: |
109 | 137 |
|
110 | | -- **[Express.js](https://expressjs.com/)** - Web Framework |
111 | | -- **[Awilix](https://github.com/jeffijoe/awilix)** - Powerful Dependency Injection container |
112 | | -- **[Jest](https://jestjs.io/)** - For the colocated testing environments |
113 | | -- **[Joi](https://joi.dev/)** - For infrastructure schema validations |
| 138 | +1. **DI Registration**: Open `src/container.js` and register any specific repository aliases or scoped usecases. |
| 139 | +2. **Route Mounting**: Mount the generated router in `src/app.js`: |
| 140 | + ```javascript |
| 141 | + app.use('/api/v1/product', container.resolve('productRoutes')); |
| 142 | + ``` |
| 143 | +3. **Detailed Implementation**: Build out the specific logic in the generated templates (which are already integrated via Awilix). |
114 | 144 |
|
115 | | -## 🤝 Contributing |
| 145 | +--- |
| 146 | + |
| 147 | +## 🤝 Contributing & Support |
116 | 148 |
|
117 | | -Contributions are always welcome! Feel free to open issues or submit Pull Requests. |
118 | | -1. Fork the repo and create your branch (`git checkout -b feature/amazing-feature`). |
119 | | -2. Commit your changes (`git commit -m 'feat: add amazing feature'`). |
120 | | -3. Push to the branch (`git push origin feature/amazing-feature`). |
121 | | -4. Open a Pull Request. |
| 149 | +We welcome contributions from the community! |
| 150 | +1. Fork the project. |
| 151 | +2. Create your Feature Branch (`git checkout -b feat/NewFeature`). |
| 152 | +3. Commit your changes (`git commit -m 'feat: Add some NewFeature'`). |
| 153 | +4. Push to the Branch (`git push origin feat/NewFeature`). |
| 154 | +5. Open a Pull Request. |
| 155 | + |
| 156 | +--- |
122 | 157 |
|
123 | 158 | ## 📝 License |
124 | 159 |
|
125 | | -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. |
| 160 | +Distributed under the **MIT License**. See `LICENSE` for more information. |
| 161 | + |
| 162 | +--- |
| 163 | +<div align="center"> |
| 164 | + <p>Built with ❤️ for modern Node.js developers</p> |
| 165 | + <sub>Copyright © 2024 saul-paulus</sub> |
| 166 | +</div> |
0 commit comments