create-stackflow 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# create-stackflow
+
+Professional interactive npm CLI for generating modern full-stack MERN applications.
+
+```bash
+npx create-stackflow
+```
+
+## What It Generates
+
+- Root npm workspace with `frontend` and `backend` packages.
+- React/Vite or Next.js frontend using the official generator.
+- JavaScript or TypeScript project files.
+- Tailwind CSS, shadcn-style component folders, dark mode, toast notifications, loading states.
+- Auth screens, protected dashboard route, Axios service layer, and CRUD task UI.
+- Express/MongoDB backend with JWT auth, bcryptjs, cookies, CORS, helmet, rate limiting, dotenv, Mongoose, and CRUD APIs.
+- Optional Swagger, Socket.IO, Winston, Morgan, Cloudinary, and multer upload structure.
+
+## CLI Architecture
+
+```text
+src/
+  cli.js                  # Commander entrypoint and bin target
+  commands/
+    create.js             # Main orchestration and success/error handling
+  generators/
+    root.js               # Root workspace, README, .gitignore
+    frontend.js           # Official frontend scaffolding + StackFlow overlay
+    backend.js            # Express/MongoDB API templates
+  utils/
+    prompts.js            # Inquirer setup questions
+    names.js              # Project naming helpers
+    template.js           # Small template writer utilities
+```
+
+## Workflow
+
+1. Print a branded CLI banner.
+2. Ask setup questions with defaults for project, frontend folder, backend folder, framework, language, UI, state, validation, auth, and optional backend features.
+3. Validate the project name with npm naming rules.
+4. Create the root workspace package.
+5. Run the official frontend generator:
+   - Vite for React.
+   - `create-next-app` for Next.js.
+6. Persist frontend dependencies using `latest`, then install them unless `--skip-install` is passed.
+7. Overlay frontend auth, CRUD, API services, reusable components, protected routes, dark mode, and dashboard UI.
+8. Generate backend structure, env files, models, controllers, routes, middleware, services, and optional integrations.
+9. Install backend and root dependencies unless skipped.
+10. Show clean next-step instructions.
+
+## Implementation Order
+
+1. CLI entrypoint and prompts.
+2. Root workspace generator.
+3. Official frontend generator integration.
+4. Backend API generator.
+5. Frontend auth/dashboard overlay.
+6. Dependency persistence and install strategy.
+7. Smoke tests and generated-app build tests.
+8. npm packaging metadata.
+
+## Template Strategy
+
+The current implementation keeps templates close to their generators so the package stays compact. As the project grows, move each template into a dedicated folder:
+
+```text
+src/templates/
+  frontend/
+    react/
+    next/
+  backend/
+    base/
+    optional/
+```
+
+Use placeholder replacement for stable values such as project name, database name, and enabled features. Keep feature generators modular so future stacks like Docker, Prisma, PostgreSQL, Redis, BullMQ, SaaS starters, AI starters, and React Native can be added without rewriting the base flow.
+
+## Dependency Strategy
+
+- Generated `package.json` files use `latest` for app dependencies so npm resolves current stable versions at generation time.
+- Official generators are invoked with `vite@latest` and `create-next-app@latest`.
+- `--skip-install` still writes dependency declarations, so users can run `npm install` later.
+- Root `npm run dev` uses npm workspaces and `concurrently`.
+
+## Auth Strategy
+
+- Backend creates users with hashed passwords via bcryptjs.
+- Login/register return JWT and set an HTTP-only cookie.
+- Protected API routes use cookie or bearer token auth.
+- Frontend stores the token for Authorization headers and redirects unauthenticated users away from protected pages.
+
+## CRUD Strategy
+
+- Backend includes a `Task` model scoped to the authenticated user.
+- API exposes list, create, update, and delete routes.
+- Frontend dashboard consumes the API through a service layer and shows loading, empty, create, and delete states.
+
+## Local Testing
+
+```bash
+npm run smoke
+node ./src/cli.js demo-stackflow --yes --skip-install
+cd demo-stackflow
+npm install
+npm run build --workspace frontend
+npm run build --workspace backend
+```
+
+For a full interactive test:
+
+```bash
+node ./src/cli.js
+```
+
+## Publishing
+
+1. Confirm `package.json` name is available on npm.
+2. Run `npm pack --dry-run`.
+3. Log in with `npm login`.
+4. Publish with `npm publish --access public`.
+5. Test from a separate folder:
+
+```bash
+npx create-stackflow@latest
+```
+
+## Naming Conventions
+
+- CLI package: `create-stackflow`.
+- Generated root package: kebab-case project name.
+- Folders: default `frontend` and `backend`, user configurable.
+- Backend files: `*.controller`, `*.routes`, `*.middleware`, `*.service`, `*.model`.
+- Frontend files: feature-first folders under `features`, shared primitives under `components/ui`, API utilities under `lib`.
+
+## Best Practices
+
+- Prefer official framework generators for baseline correctness.
+- Keep generated code understandable for beginners.
+- Keep feature generation modular and composable.
+- Store env defaults locally but never commit real secrets in generated apps.
+- Use npm workspaces for simple root-level development.
+- Keep optional integrations isolated so they can be removed or expanded cleanly.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-stackflow",
+  "version": "1.0.0",
+  "description": "Interactive CLI for generating modern full-stack MERN applications.",
+  "type": "module",
+  "bin": {
+    "create-stackflow": "./src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node ./src/cli.js",
+    "dev": "node ./src/cli.js",
+    "smoke": "node ./src/cli.js --help"
+  },
+  "keywords": [
+    "create",
+    "mern",
+    "cli",
+    "react",
+    "nextjs",
+    "express",
+    "mongodb",
+    "stackflow"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "concurrently": "^9.2.1",
+    "execa": "^9.6.0",
+    "fs-extra": "^11.3.2",
+    "inquirer": "^12.10.0",
+    "ora": "^9.0.0",
+    "validate-npm-package-name": "^6.0.2"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import { createStackFlow } from "./commands/create.js";
+
+const program = new Command();
+
+program
+  .name("create-stackflow")
+  .description("Generate a production-minded MERN starter with frontend, backend, auth, CRUD, and dashboard UI.")
+  .version("1.0.0")
+  .argument("[project-name]", "project folder name")
+  .option("--skip-install", "generate files without installing dependencies")
+  .option("--yes", "use recommended defaults")
+  .action(async (projectName, options) => {
+    try {
+      await createStackFlow({ projectName, ...options });
+    } catch (error) {
+      console.error(chalk.red("\nStackFlow generation failed."));
+      console.error(chalk.dim(error?.stack || error?.message || error));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/commands/create.js

@@ -0,0 +1,149 @@
+import path from "node:path";
+import process from "node:process";
+import chalk from "chalk";
+import fs from "fs-extra";
+import ora from "ora";
+import validatePackageName from "validate-npm-package-name";
+import { execa } from "execa";
+import { askQuestions } from "../utils/prompts.js";
+import { createRootFiles } from "../generators/root.js";
+import { createBackend } from "../generators/backend.js";
+import { createFrontend } from "../generators/frontend.js";
+import { formatName } from "../utils/names.js";
+
+export async function createStackFlow(options) {
+  printBanner();
+
+  const answers = options.yes
+    ? recommendedDefaults(options.projectName)
+    : await askQuestions(options.projectName);
+
+  const projectName = formatName(answers.projectName);
+  const validation = validatePackageName(projectName);
+  if (!validation.validForNewPackages) {
+    throw new Error(`Invalid project name "${projectName}": ${(validation.errors || validation.warnings || []).join(", ")}`);
+  }
+
+  const projectDir = path.resolve(process.cwd(), projectName);
+  if (await fs.pathExists(projectDir)) {
+    const existing = await fs.readdir(projectDir);
+    if (existing.length > 0) {
+      throw new Error(`Target folder already exists and is not empty: ${projectDir}`);
+    }
+  }
+
+  const context = {
+    ...answers,
+    projectName,
+    projectDir,
+    frontendDir: path.join(projectDir, answers.frontendName || "frontend"),
+    backendDir: path.join(projectDir, answers.backendName || "backend"),
+    skipInstall: Boolean(options.skipInstall),
+    databaseName: projectName.replace(/[^a-zA-Z0-9_-]/g, ""),
+    packageManager: "npm"
+  };
+
+  await fs.ensureDir(projectDir);
+
+  await step("Creating root workspace", () => createRootFiles(context));
+  await createFrontend(context);
+  await createBackend(context);
+
+  if (!context.skipInstall) {
+    await step("Installing root workspace dependencies", () =>
+      execa("npm", ["install"], { cwd: projectDir, stdio: "ignore" })
+    );
+  }
+
+  printSuccess(context);
+}
+
+function recommendedDefaults(projectName) {
+  return {
+    projectName: projectName || "stackflow-app",
+    frontendName: "frontend",
+    backendName: "backend",
+    frontend: "react",
+    language: "typescript",
+    backendLanguage: "javascript",
+    styling: "tailwind",
+    tailwind: true,
+    uiLibrary: "shadcn",
+    shadcn: true,
+    iconLibrary: "lucide-react",
+    router: true,
+    state: "zustand",
+    dataFetching: "axios",
+    tanstackQuery: false,
+    form: "react-hook-form",
+    validation: "zod",
+    axios: true,
+    authPages: true,
+    protectedRoutes: true,
+    darkMode: true,
+    animation: "none",
+    toast: "sonner",
+    chart: "none",
+    dragDropUpload: "none",
+    eslint: true,
+    prettier: true,
+    backendFramework: "Express.js",
+    database: "MongoDB",
+    orm: "Mongoose",
+    authStrategy: "JWT",
+    passwordHashing: "bcryptjs",
+    fileUpload: "Multer",
+    backendValidation: "None",
+    securityPackages: ["helmet", "cors", "express-rate-limit", "hpp"],
+    cookieParser: true,
+    logging: "Morgan",
+    swagger: true,
+    socketio: false,
+    winston: false,
+    morgan: true,
+    cloudinary: false,
+    multer: true,
+    helmet: true,
+    cors: true,
+    rateLimit: true,
+    hpp: true,
+    emailService: "None",
+    crudModules: ["users", "products", "categories", "orders", "blogs"],
+    authFeatures: ["login", "register", "forgot-password", "reset-password", "email-verification", "roles", "refresh-tokens"],
+    adminDashboard: true
+  };
+}
+
+async function step(text, task) {
+  const spinner = ora(text).start();
+  try {
+    await task();
+    spinner.succeed(text);
+  } catch (error) {
+    spinner.fail(text);
+    throw error;
+  }
+}
+
+function printBanner() {
+  console.log();
+  console.log(chalk.cyan.bold("create-stackflow"));
+  console.log(chalk.dim("Modern MERN app generator with auth, CRUD, dashboard, and production-ready structure."));
+  console.log();
+}
+
+function printSuccess(context) {
+  const frontend = path.basename(context.frontendDir);
+  const backend = path.basename(context.backendDir);
+  console.log();
+  console.log(chalk.green.bold("StackFlow app created successfully."));
+  console.log();
+  console.log(chalk.white("Next steps:"));
+  console.log(chalk.cyan(`  cd ${context.projectName}`));
+  console.log(chalk.cyan("  npm run dev"));
+  console.log();
+  console.log(chalk.dim(`Frontend: ${frontend}`));
+  console.log(chalk.dim(`Backend:  ${backend}`));
+  console.log(chalk.dim("MongoDB:  mongodb://127.0.0.1:27017/" + context.databaseName));
+  console.log();
+}