Welcome to the **Modulator Framework**—a modern, TypeScript-first, modular monolith framework for Node.js applications. This package (`@modulator/create-app`) provides a CLI tool to scaffold new Modulator projects with best practices, modular architecture
npm install @modulator/create-app@modulator/create-app)@modulator/create-app) provides a CLI tool to scaffold new Modulator projects with best practices, modular architecture, and Prisma ORM integration out of the box.
sh
npx @modulator/create-app my-app
cd my-app
npm run cli -- setup:upgrade
npm start
`
$3
`
my-app/
config/
modules.json # Tracks enabled/disabled modules
modules/
/ # Each module in its own folder
module.json # Module manifest (name, version, dependencies, etc)
controller/
... # Controllers for this module
model/
module_schema.prisma # Prisma schema for this module
routes/ # Route registration (auto-discovered)
events/ # Event handlers (auto-discovered)
prisma/
schema.prisma # Merged Prisma schema
src/
build/
app.ts # App entry point
package.json
tsconfig.json
`
---
📄 File Naming Conventions
Recommended: Use lowercase, descriptive file names for all files in your modules. For example:
- userRoutes.ts, adminRoutes.ts (routes)
- userEvents.ts, emailEvents.ts (events)
- postController.ts, userController.ts (controllers)
This helps keep your codebase consistent and easy to navigate.
---
🧩 Creating a New Module
1. Create a new folder in modules/ (e.g., modules/blog/)
2. Add a module.json manifest:
`json
{
"name": "blog",
"version": "1.0.0",
"dependencies": ["user"]
}
`
3. Add controllers in controller/ (e.g., postController.ts)
4. Add a Prisma schema in model/module_schema.prisma (optional)
5. Add routes and events - auto-discovery handles registration automatically!
`typescript
// routes/Routes.ts - automatically discovered
export function register(app: any) {
app.get('/posts', postController);
}
// events/Events.ts - automatically discovered
export function register(eventBus: any) {
eventBus.on('post.created', handlePostCreated);
}
`
6. Enable the module:
`sh
npm run cli -- module:enable blog
`
7. Run setup/upgrade to merge schemas and run migrations:
`sh
npm run cli -- setup:upgrade
`
---
🛡️ CLI Commands
- setup:upgrade — Discover enabled modules and run their migrations
- module:list — List all modules and their status
- module:enable — Enable a module (checks dependencies)
- module:disable — Disable a module (prevents if dependents exist)
- module:info — Show detailed info about a module
- db:migrate — Merge all module schemas and run Prisma migration
---
🏗️ Best Practices
- Keep modules independent: Avoid tight coupling between modules
- Use dependencies in module.json` to declare required modules