Production-grade CLI code generator for Node.js backend modules with strict conventions and mandatory Swagger documentation
npm install echo-crud-factory> Production-grade CLI code generator for Node.js backend modules with strict conventions and mandatory Swagger documentation



Echo CRUD Factory is an enterprise-ready CLI tool that generates consistent, opinionated, production-ready CRUD modules for Node.js backends. It enforces strict naming conventions, provides mandatory Swagger documentation, and supports multiple ORMs and databases.
✅ Schema-Driven Generation - Single JSON schema as source of truth
✅ Strict Naming Conventions - Enforced snake_case, kebab-case, PascalCase
✅ Mandatory Swagger/OpenAPI 3.x - Complete API documentation for every endpoint
✅ Multi-ORM Support - Sequelize, TypeORM, Prisma
✅ Multi-Database Support - MySQL, PostgreSQL, SQLite, MariaDB, MSSQL
✅ Yup Validation - 1:1 mapping to Yup API with strict validation
✅ Express-First - Framework-agnostic but optimized for Express
✅ Deterministic Output - Same input always produces same output
✅ Rollback on Failure - Automatic cleanup if generation fails
✅ Dry-Run Mode - Preview files before writing
- Node.js: v22.0.0 or higher
- npm: v9.0.0 or higher
Install as a dev dependency in your project:
``bash`
npm install --save-dev echo-crud-factory
Important: With local installation, you must use npx prefix for all commands:
`bash`
npx echo-crud-factory generate --entity=User --fields=./schema.json
`bash`
npx echo-crud-factory init --interactive
This creates a .echocrudfactoryrc file with your preferences:
`json`
{
"orm": "sequelize",
"database": "mysql",
"apiCase": "snake_case",
"dbCase": "snake_case",
"withService": true,
"withRepository": false,
"withSoftDelete": true,
"withPagination": true,
"withTimestamps": true,
"swaggerEnabled": true
}
Create user-schema.json:
`json`
[
{
"column_name": "id",
"type": "primary"
},
{
"column_name": "first_name",
"type": "string",
"mandatory": true,
"validations": ["min:3", "max:50", "regex:/^[a-zA-Z\\s]+$/"]
},
{
"column_name": "email",
"type": "string",
"mandatory": true,
"unique": true,
"validations": ["email"]
},
{
"column_name": "age",
"type": "integer",
"validations": ["min:18", "max:120"]
},
{
"column_name": "status",
"type": "enum",
"enum_values": ["active", "inactive", "suspended"],
"default_value": "active"
}
]
`bash`
npx echo-crud-factory generate --entity=User --fields=./user-schema.json
`
src/
├── controllers/
│ └── user.controller.js
├── models/
│ └── user.model.js
├── routes/
│ └── user.routes.js
├── validators/
│ └── user.validator.js
└── swagger/
└── user.swagger.js
db/
└── migrations/
└── 20260113185550-create-users.js
`
Generate CRUD module for an entity.
`bash`
npx echo-crud-factory generate --entity=User --fields=./schema.json [options]
Options:
- --entity - Entity name in PascalCase (required)--table
- - Table name in snake_case (optional, auto-generated)--fields
- - Path to JSON schema file (required)--dry-run
- - Preview files without writing--force
- - Overwrite existing files--verbose
- - Enable verbose logging
Examples:
`bashBasic generation
npx echo-crud-factory generate --entity=User --fields=./user-schema.json
$3
Initialize Echo CRUD Factory configuration.
`bash
npx echo-crud-factory init [--interactive]
`Options:
-
--interactive - Interactive configuration setup$3
Validate schema file.
`bash
npx echo-crud-factory check --fields=./schema.json
`$3
Check system dependencies and configuration.
`bash
npx echo-crud-factory doctor
`$3
View or update configuration.
`bash
Show current configuration
npx echo-crud-factory config --showUpdate configuration
npx echo-crud-factory config --set orm=typeorm
npx echo-crud-factory config --set withService=false
`Schema File Specification
$3
`typescript
{
"column_name": string, // snake_case (required)
"type": ColumnType, // (required)
"mandatory": boolean, // (optional)
"unique": boolean, // (optional)
"default_value": any, // (optional)
"validations": string[], // (optional)
"enum_values": string[], // (required for enum type)
"length": number, // (optional, for string)
"precision": number, // (optional, for float)
"scale": number, // (optional, for float)
"foreign_key": { // (optional)
"table": string,
"column": string,
"on_delete": string,
"on_update": string
},
"index": boolean // (optional)
}
`$3
-
primary - Primary key (BIGINT, auto-increment)
- string - VARCHAR
- text - TEXT
- integer - INTEGER
- bigint - BIGINT
- float - FLOAT/DECIMAL
- boolean - BOOLEAN
- date - DATE/DATETIME
- enum - ENUM (requires enum_values)
- json - JSON$3
All validation rules map 1:1 to Yup API:
-
required - Field is required
- email - Valid email format
- url - Valid URL format
- uuid - Valid UUID format
- min:N - Minimum length/value
- max:N - Maximum length/value
- length:N - Exact length
- matches:/pattern/ or regex:/pattern/ - Regex pattern
- oneOf:val1,val2 - One of specified values
- positive - Positive number
- negative - Negative number
- integer - Integer number
- lessThan:N - Less than value
- moreThan:N - More than valueExample:
`json
{
"column_name": "username",
"type": "string",
"mandatory": true,
"validations": [
"min:3",
"max:20",
"regex:/^[a-zA-Z0-9_]+$/"
]
}
`Naming Conventions (Strictly Enforced)
| Layer | Convention | Example |
|-------|------------|---------|
| Entity (input) | PascalCase |
User, ProductCategory |
| API request/response | snake_case | first_name, created_at |
| DTOs | snake_case | user_id, order_total |
| Yup schemas | snake_case | email, phone_number |
| Database columns | snake_case | first_name, created_at |
| Database tables | snake_case (plural) | users, product_categories |
| Files & folders | kebab-case | user.controller.js, product-category.routes.js |Any violation will fail generation with a descriptive error.
Generated Code Structure
$3
Express-compatible controllers with:
- Async/await
- Centralized error handling
- snake_case DTOs
- CRUD methods:
create, list, get_by_id, update, delete/soft_delete$3
ORM models with:
- snake_case columns
- Primary key:
id (BIGINT)
- Timestamps: created_at, updated_at, deleted_at
- Proper data types and constraints$3
RESTful endpoints:
-
POST /api/users - Create
- GET /api/users - List with pagination
- GET /api/users/:id - Get by ID
- PUT /api/users/:id - Update
- DELETE /api/users/:id - Delete
- POST /api/users/:id/restore - Restore (if soft delete enabled)$3
Yup validation schemas:
- Create schema (mandatory fields required)
- Update schema (all fields optional)
- Query schema (for filtering)
- Pagination schema
$3
OpenAPI 3.x documentation:
- Complete request/response schemas
- All parameters documented
- Success and error responses
- Tags for organization
$3
Database migrations:
- Timestamp-based naming
- Up/down migrations
- Indexes and constraints
- Foreign keys
Configuration Options
$3
`json
{
"orm": "sequelize", // sequelize | typeorm | prisma
"database": "mysql", // mysql | postgresql | sqlite | mariadb | mssql
"apiCase": "snake_case", // Always snake_case (enforced)
"dbCase": "snake_case", // Always snake_case (enforced)
"withService": true, // Generate service layer
"withRepository": false, // Generate repository layer
"withSoftDelete": true, // Enable soft delete
"withPagination": true, // Enable pagination
"withTimestamps": true, // Add created_at, updated_at
"swaggerEnabled": true // Always true (mandatory)
}
`Supported ORMs
$3
`bash
npm install sequelize mysql2
`$3
`bash
npm install typeorm reflect-metadata mysql2
`$3
`bash
npm install @prisma/client
npm install -D prisma
`Integration Example
$3
`javascript
import express from 'express';
import userRoutes from './routes/user.routes.js';
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';const app = express();
app.use(express.json());
// Routes
app.use('/api/users', userRoutes);
// Swagger
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'API Documentation',
version: '1.0.0',
},
},
apis: ['./src/routes/.js', './src/swagger/.js'],
};
const swaggerSpec = swaggerJsdoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.listen(3000, () => {
console.log('Server running on port 3000');
});
`Best Practices
1. Always use schema files - Don't manually write CRUD code
2. Validate schemas - Run
echo-crud-factory check before generating
3. Use dry-run - Preview files with --dry-run flag
4. Version control schemas - Keep schema files in git
5. Review generated code - Always review before committing
6. Run migrations - Don't forget to run database migrations
7. Test endpoints - Use generated Swagger docs for testingTroubleshooting
$3
`
✗ Node.js v22 or higher is required
`Solution: Upgrade Node.js to v22 or higher.
$3
`
✗ Column name "firstName" must be in snake_case format
`Solution: Use snake_case for all column names:
first_name.$3
`
✗ File already exists: src/controllers/user.controller.js
`Solution: Use
--force flag to overwrite or manually delete the file.$3
`
✗ Required dependency not found: sequelize
`Solution: Install required dependencies:
`bash
npm install sequelize mysql2
``- [ ] TypeORM model generator
- [ ] Prisma schema generator
- [ ] Service layer generator
- [ ] Repository layer generator
- [ ] Test file generator
- [ ] OpenAPI to Postman export
- [ ] Custom template support
- [ ] Plugin system
- [ ] GraphQL support
Contributions are welcome! Please read our Contributing Guide for details.
MIT © Master Builder Team
---
Built with ❤️ for backend developers who value consistency and quality.