create-flex-stack 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# create-flex-stack
+
+Production-ready TypeScript project generator for Express APIs and optional React frontends.
+
+## Usage
+
+```bash
+npm create flex-stack@latest
+```
+
+Or run the binary directly:
+
+```bash
+npx create-flex-stack@latest
+```
+
+The CLI will ask for the project name and stack options, then generate the project and install dependencies.
+
+## Features
+
+- Express + TypeScript backend
+- Optional React + Vite frontend
+- Architecture choices: Layered/MVC, VMC, Modular, Clean Architecture, Hexagonal Architecture
+- Database choices: PostgreSQL, MySQL, SQLite, MongoDB
+- ORM choices: Prisma, TypeORM, Mongoose
+- Optional JWT auth, RBAC, Swagger, rate limiting, file uploads, Docker, Redis and Jest
+- Generated README with the commands needed for the selected stack
+
+## Generated Project
+
+After generation, enter the project folder and follow its generated README. For Prisma projects, the most common commands are:
+
+```bash
+npm run db:generate
+npm run db:push
+npm run dev
+```
+
+For Docker deployments with Prisma:
+
+```bash
+npm run db:generate
+npm run db:migrate:deploy
+docker compose up --build
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+import { intro, outro, text, select, confirm, isCancel, cancel, spinner } from '@clack/prompts';
+import pc from 'picocolors';
+import { generateProject } from './utils/generator.js';
+async function main() {
+    intro(pc.bold(pc.cyan('CREATE-FLEX-STACK: Ultimate Full-Stack Boilerplate Generator')));
+    // 1. Project Name
+    const projectName = await text({
+        message: 'Enter your project name:',
+        placeholder: 'my-ultimate-stack',
+        initialValue: 'my-ultimate-stack',
+        validate(value) {
+            if (value.length === 0)
+                return 'Project name is required';
+            if (/[<>:"/\\|?*]/.test(value))
+                return 'Project name contains invalid characters';
+        },
+    });
+    if (isCancel(projectName)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 2. Choose Architecture
+    const architecture = await select({
+        message: 'Choose your backend architecture:',
+        options: [
+            { value: 'layered', label: 'Traditional Layered (MVC)', hint: 'controllers, services, repositories, models, routes' },
+            { value: 'vmc', label: 'VMC (View, Model, Controller)', hint: 'view DTOs, model/business logic, controllers, routes' },
+            { value: 'modular', label: 'Modular / Feature-Based', hint: 'organized by feature folder: users, auth, products' },
+            { value: 'clean', label: 'Clean Architecture', hint: 'presentation, application, domain, infrastructure, shared' },
+            { value: 'hexagonal', label: 'Hexagonal Architecture (Ports & Adapters)', hint: 'domain, application, ports, adapters' },
+        ],
+    });
+    if (isCancel(architecture)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 3. Backend Framework
+    const frameworkChoice = await select({
+        message: 'Choose your backend framework:',
+        options: [
+            { value: 'express', label: 'ExpressJS (TypeScript) [Fully Implemented]' },
+            { value: 'nestjs', label: pc.yellow('NestJS (Coming Soon) [Fallback to Express]') },
+            { value: 'fastify', label: pc.yellow('Fastify (Coming Soon) [Fallback to Express]') },
+            { value: 'hono', label: pc.yellow('Hono (Coming Soon) [Fallback to Express]') },
+            { value: 'koa', label: pc.yellow('Koa (Coming Soon) [Fallback to Express]') },
+            { value: 'adonis', label: pc.yellow('AdonisJS (Coming Soon) [Fallback to Express]') },
+        ],
+    });
+    if (isCancel(frameworkChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    if (frameworkChoice !== 'express') {
+        console.log(pc.yellow(`\n⚠ Framework "${frameworkChoice}" is coming soon. Defaulting backend to ExpressJS.`));
+    }
+    const framework = 'express';
+    // 4. Database Selection
+    const databaseChoice = await select({
+        message: 'Choose your database:',
+        options: [
+            { value: 'postgres', label: 'PostgreSQL' },
+            { value: 'mysql', label: 'MySQL' },
+            { value: 'sqlite', label: 'SQLite' },
+            { value: 'mongodb', label: 'MongoDB' },
+            { value: 'mariadb', label: pc.yellow('MariaDB (Coming Soon) [Fallback to MySQL]') },
+            { value: 'firestore', label: pc.yellow('Firestore (Coming Soon) [Fallback to MongoDB]') },
+            { value: 'dynamodb', label: pc.yellow('DynamoDB (Coming Soon) [Fallback to MongoDB]') },
+        ],
+    });
+    if (isCancel(databaseChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    let database = 'postgres';
+    if (databaseChoice === 'postgres' || databaseChoice === 'mysql' || databaseChoice === 'sqlite' || databaseChoice === 'mongodb') {
+        database = databaseChoice;
+    }
+    else if (databaseChoice === 'mariadb') {
+        console.log(pc.yellow('\n⚠ MariaDB is coming soon. Defaulting to MySQL configuration.'));
+        database = 'mysql';
+    }
+    else {
+        console.log(pc.yellow(`\n⚠ DB "${databaseChoice}" is coming soon. Defaulting to MongoDB configuration.`));
+        database = 'mongodb';
+    }
+    // 5. ORM Selection based on database
+    let ormOptions = [];
+    if (database === 'postgres' || database === 'mysql') {
+        ormOptions = [
+            { value: 'prisma', label: 'Prisma ORM [Default]' },
+            { value: 'typeorm', label: 'TypeORM' },
+            { value: 'sequelize', label: pc.yellow('Sequelize (Coming Soon) [Fallback to Prisma]') },
+            { value: 'drizzle', label: pc.yellow('Drizzle ORM (Coming Soon) [Fallback to Prisma]') },
+        ];
+    }
+    else if (database === 'sqlite') {
+        ormOptions = [
+            { value: 'prisma', label: 'Prisma ORM [Default]' },
+            { value: 'typeorm', label: 'TypeORM' },
+        ];
+    }
+    else {
+        // mongodb
+        ormOptions = [
+            { value: 'mongoose', label: 'Mongoose ODM [Default]' },
+            { value: 'prisma', label: 'Prisma ORM' },
+        ];
+    }
+    const ormChoice = await select({
+        message: 'Choose your ORM/ODM:',
+        options: ormOptions,
+    });
+    if (isCancel(ormChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    let orm = 'prisma';
+    if (ormChoice === 'prisma' || ormChoice === 'typeorm' || ormChoice === 'mongoose') {
+        orm = ormChoice;
+    }
+    else {
+        console.log(pc.yellow(`\n⚠ ORM "${ormChoice}" is coming soon. Defaulting to Prisma ORM.`));
+        orm = 'prisma';
+    }
+    // 6. Frontend Framework Choice
+    const frontendChoice = await select({
+        message: 'Choose frontend framework:',
+        options: [
+            { value: 'none', label: 'None (Backend API only)' },
+            { value: 'react', label: 'React (Vite + TypeScript) [Fully Implemented]' },
+            { value: 'nextjs', label: pc.yellow('Next.js (Coming Soon) [Fallback to React]') },
+            { value: 'vue', label: pc.yellow('Vue 3 (Coming Soon) [Fallback to React]') },
+            { value: 'angular', label: pc.yellow('Angular (Coming Soon) [Fallback to React]') },
+        ],
+    });
+    if (isCancel(frontendChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    let frontend = false;
+    if (frontendChoice === 'react') {
+        frontend = true;
+    }
+    else if (frontendChoice !== 'none') {
+        console.log(pc.yellow(`\n⚠ Frontend "${frontendChoice}" is coming soon. Defaulting to React client.`));
+        frontend = true;
+    }
+    // If frontend is React, show UI and State prompts
+    if (frontend) {
+        const uiChoice = await select({
+            message: 'Choose UI library:',
+            options: [
+                { value: 'tailwind', label: 'TailwindCSS + shadcn/ui [Fully Implemented]' },
+                { value: 'mui', label: pc.yellow('Material UI (Coming Soon) [Fallback to TailwindCSS]') },
+                { value: 'chakra', label: pc.yellow('Chakra UI (Coming Soon) [Fallback to TailwindCSS]') },
+            ],
+        });
+        if (isCancel(uiChoice)) {
+            cancel('Generation cancelled.');
+            process.exit(0);
+        }
+        const stateChoice = await select({
+            message: 'Choose State management:',
+            options: [
+                { value: 'zustand', label: 'Zustand [Fully Implemented]' },
+                { value: 'redux', label: pc.yellow('Redux Toolkit (Coming Soon) [Fallback to Zustand]') },
+            ],
+        });
+        if (isCancel(stateChoice)) {
+            cancel('Generation cancelled.');
+            process.exit(0);
+        }
+    }
+    // 7. Validation Library
+    const validationChoice = await select({
+        message: 'Choose validation library:',
+        options: [
+            { value: 'zod', label: 'Zod' },
+            { value: 'joi', label: 'Joi' },
+            { value: 'yup', label: pc.yellow('Yup (Coming Soon) [Fallback to Zod]') },
+        ],
+    });
+    if (isCancel(validationChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    let validation = 'zod';
+    if (validationChoice === 'zod' || validationChoice === 'joi') {
+        validation = validationChoice;
+    }
+    else {
+        console.log(pc.yellow(`\n⚠ Validation library "${validationChoice}" is coming soon. Defaulting to Zod.`));
+        validation = 'zod';
+    }
+    // 8. Auth Module
+    const authChoice = await confirm({
+        message: 'Generate User & Auth module? (JWT, Login, Signup, Refresh Tokens)',
+        initialValue: true,
+    });
+    if (isCancel(authChoice)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    const auth = Boolean(authChoice);
+    let rbac = false;
+    if (auth) {
+        const rbacChoice = await confirm({
+            message: 'Include Role-Based Access Control (RBAC) middleware?',
+            initialValue: true,
+        });
+        if (isCancel(rbacChoice)) {
+            cancel('Generation cancelled.');
+            process.exit(0);
+        }
+        rbac = Boolean(rbacChoice);
+    }
+    // 9. File Upload
+    const fileUpload = await confirm({
+        message: 'Include File Upload module? (Multer setup)',
+        initialValue: true,
+    });
+    if (isCancel(fileUpload)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 10. Swagger Docs
+    const swagger = await confirm({
+        message: 'Include Swagger API Documentation UI?',
+        initialValue: true,
+    });
+    if (isCancel(swagger)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 11. Docker
+    const docker = await confirm({
+        message: 'Include Docker & docker-compose configurations?',
+        initialValue: true,
+    });
+    if (isCancel(docker)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 12. Rate Limiting
+    const rateLimiting = await confirm({
+        message: 'Include API Rate Limiting security middleware?',
+        initialValue: true,
+    });
+    if (isCancel(rateLimiting)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 13. Caching (Redis)
+    const caching = await confirm({
+        message: 'Include Caching layer integration (Redis client)?',
+        initialValue: false,
+    });
+    if (isCancel(caching)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    // 14. Testing
+    const testing = await confirm({
+        message: 'Include testing setup? (Jest)',
+        initialValue: true,
+    });
+    if (isCancel(testing)) {
+        cancel('Generation cancelled.');
+        process.exit(0);
+    }
+    const options = {
+        projectName: projectName,
+        architecture: architecture,
+        framework,
+        database,
+        orm,
+        frontend,
+        auth,
+        docker,
+        validation,
+        rateLimiting,
+        swagger,
+        caching,
+        rbac,
+        fileUpload,
+        testing,
+    };
+    const s = spinner();
+    let lastMessage = '';
+    try {
+        await generateProject(options, (msg, status) => {
+            if (status === 'start') {
+                lastMessage = msg;
+                s.start(msg);
+            }
+            else if (status === 'stop') {
+                s.stop(pc.green(`✔ ${lastMessage || msg}`));
+            }
+            else if (status === 'error') {
+                s.stop(pc.red(`❌ ${msg}`));
+            }
+            else {
+                s.message(msg);
+            }
+        });
+        outro(pc.bold(pc.green('🎉 Project generated successfully!')));
+        // Output next steps
+        console.log(pc.cyan('\nNext Steps:'));
+        console.log(`  cd ${projectName}`);
+        if (frontend) {
+            console.log('  npm install       (at root to install workspace dependencies)');
+            console.log('  npm run dev       (starts both backend and frontend concurrently)');
+        }
+        else {
+            console.log('  npm install');
+            console.log('  npm run dev');
+        }
+        if (orm === 'prisma') {
+            console.log('  npm run db:push   (or npx prisma db push from backend)');
+        }
+        console.log('\nEnjoy building your application!\n');
+    }
+    catch (error) {
+        s.stop(pc.red('❌ Project generation failed.'));
+        outro(pc.red(`Error: ${error.message}`));
+        process.exit(1);
+    }
+}
+main();