@surajprasad/create-starterkit 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @surajprasad/create-starterkit
+
+A production-ready MERN (MongoDB, Express, React, Node) Starterkit generator. Features include optional JWT Auth, Email service (Nodemailer), and Docker support. 
+
+## Usage
+
+To create a new project:
+
+```bash
+npm create @surajprasad/starterkit@latest my-app
+```
+
+Or using `npx`:
+
+```bash
+npx @surajprasad/create-starterkit@latest my-app
+```
+
+## Features
+
+- **MERN Stack**: Modern backend with Express/MongoDB, and frontend with Vite or Next.js.
+- **JWT Authentication**: Built-in authentication module with sign-in, sign-up, and forgot-password flows (optional).
+- **Email Service**: Integration with Nodemailer for sending verification and transactional emails (optional).
+- **Docker Ready**: One-command setup with `docker-compose` (optional).
+- **Interactive CLI**: Choose only the features you need.
+- **Fast Development**: Pre-configured environment variables and folder hierarchy.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import chalk from "chalk";
+import fs from "fs-extra";
+import prompts from "prompts";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const TEMPLATE_ROOT = path.join(__dirname, "templates");
+
+const usage = () => {
+  const cmd = chalk.cyan("npm create @surajprasad/starterkit@latest my-app-name");
+  return `Usage: ${cmd}`;
+};
+
+const parseArgs = (argv) => {
+  const flags = new Set(argv.slice(3));
+  return {
+    yes: flags.has("--yes") || flags.has("--defaults") || flags.has("-y"),
+    frontend: flags.has("--frontend=next")
+      ? "next"
+      : flags.has("--frontend=vite")
+        ? "vite"
+        : undefined,
+    auth: flags.has("--no-auth") ? false : flags.has("--auth") ? true : undefined,
+    email: flags.has("--no-email") ? false : flags.has("--email") ? true : undefined,
+    docker: flags.has("--docker") ? true : flags.has("--no-docker") ? false : undefined
+  };
+};
+
+const isValidPackageName = (name) => {
+  // npm package name-ish; allow scoped? not needed here
+  return /^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$/.test(name);
+};
+
+const readJson = async (filePath) => fs.readJson(filePath);
+const writeJson = async (filePath, data) => fs.writeJson(filePath, data, { spaces: 2 });
+
+const safeRemove = async (targetPath) => {
+  try {
+    await fs.remove(targetPath);
+  } catch {
+    // ignore
+  }
+};
+
+const replaceInFile = async (filePath, replacements) => {
+  const exists = await fs.pathExists(filePath);
+  if (!exists) return;
+  let content = await fs.readFile(filePath, "utf8");
+  for (const { from, to } of replacements) {
+    content = content.replace(from, to);
+  }
+  await fs.writeFile(filePath, content, "utf8");
+};
+
+const setPackageName = async (packageJsonPath, newName) => {
+  const pkg = await readJson(packageJsonPath);
+  pkg.name = newName;
+  await writeJson(packageJsonPath, pkg);
+};
+
+const setRootPackageNameIfPresent = async (appDir, appName) => {
+  const rootPkgPath = path.join(appDir, "package.json");
+  if (!(await fs.pathExists(rootPkgPath))) return;
+  await setPackageName(rootPkgPath, appName);
+};
+
+const ensureEmptyDirDoesNotExist = async (targetDir) => {
+  if (await fs.pathExists(targetDir)) {
+    console.error(chalk.red(`Error: folder already exists: ${targetDir}`));
+    process.exit(1);
+  }
+};
+
+const renderNextSteps = ({ appName, appDir, includeDocker }) => {
+  const cdCmd = chalk.cyan(`cd ${appName}`);
+  const backendInstall = chalk.cyan("cd backend && npm install");
+  const frontendInstall = chalk.cyan("cd frontend && npm install");
+  const backendRun = chalk.cyan("npm run dev");
+  const frontendRun = chalk.cyan("npm run dev");
+
+  console.log("");
+  console.log(chalk.green("Success!"), `Created ${chalk.bold(appName)} at ${appDir}`);
+  console.log("");
+  console.log(chalk.bold("Next steps:"));
+  console.log(`- ${cdCmd}`);
+  if (includeDocker) {
+    console.log(`- ${chalk.cyan("cp backend/.env.example backend/.env")}`);
+    console.log(`- ${chalk.cyan("docker compose up --build")}`);
+  } else {
+    console.log(`- ${backendInstall}`);
+    console.log(`- ${chalk.cyan("cp backend/.env.example backend/.env")}`);
+    console.log(`- ${chalk.gray("(in one terminal)")} ${backendRun}`);
+    console.log(`- ${frontendInstall}`);
+    console.log(`- ${chalk.cyan("cp frontend/.env.example frontend/.env")}`);
+    console.log(`- ${chalk.gray("(in another terminal)")} ${frontendRun}`);
+  }
+  console.log("");
+};
+
+const generateDockerCompose = async ({ appDir }) => {
+  const compose = `version: '3.8'
+services:
+  backend:
+    build: ./backend
+    ports:
+      - 5000:5000
+    env_file:
+      - ./backend/.env
+    depends_on:
+      - mongodb
+  frontend:
+    build: ./frontend
+    ports:
+      - 5173:5173
+  mongodb:
+    image: mongo:6
+    ports:
+      - 27017:27017
+    volumes:
+      - mongo_data:/data/db
+volumes:
+  mongo_data:
+`;
+  await fs.writeFile(path.join(appDir, "docker-compose.yml"), compose, "utf8");
+};
+
+const main = async () => {
+  const appName = process.argv[2];
+  const flags = parseArgs(process.argv);
+
+  if (!appName) {
+    console.error(chalk.red("Error: missing app name."));
+    console.log(usage());
+    process.exit(1);
+  }
+
+  if (!isValidPackageName(appName)) {
+    console.error(chalk.red(`Error: invalid app name "${appName}".`));
+    console.error(chalk.gray("Use lowercase letters, numbers, dashes, underscores."));
+    process.exit(1);
+  }
+
+  const appDir = path.resolve(process.cwd(), appName);
+  await ensureEmptyDirDoesNotExist(appDir);
+
+  const promptQuestions = [
+    {
+      type: "select",
+      name: "stack",
+      message: "Select a stack",
+      choices: [{ title: "MERN (MongoDB, Express, React, Node)", value: "mern" }],
+      initial: 0
+    },
+    {
+      type: "select",
+      name: "frontend",
+      message: "Select a frontend",
+      choices: [
+        { title: "Vite + React", value: "vite" },
+        { title: "Next.js", value: "next" }
+      ],
+      initial: 0
+    },
+    {
+      type: "toggle",
+      name: "auth",
+      message: "Include JWT Auth?",
+      initial: true,
+      active: "yes",
+      inactive: "no"
+    },
+    {
+      type: "toggle",
+      name: "email",
+      message: "Include Email Service (Nodemailer)?",
+      initial: true,
+      active: "yes",
+      inactive: "no"
+    },
+    {
+      type: "toggle",
+      name: "docker",
+      message: "Include Docker?",
+      initial: false,
+      active: "yes",
+      inactive: "no"
+    }
+  ];
+
+  const answers = flags.yes
+    ? {
+        stack: "mern",
+        frontend: flags.frontend ?? "vite",
+        auth: flags.auth ?? true,
+        email: flags.email ?? true,
+        docker: flags.docker ?? false
+      }
+    : await prompts(promptQuestions, {
+        onCancel: () => {
+          console.log("");
+          console.log(chalk.yellow("Cancelled."));
+          process.exit(1);
+        }
+      });
+
+  let includeAuth = Boolean(answers.auth);
+  const includeEmail = Boolean(answers.email);
+  const includeDocker = Boolean(answers.docker);
+
+  if (!includeAuth && includeEmail) {
+    includeAuth = true;
+    console.log(
+      chalk.yellow(
+        "Note: Email service requires Auth (admin-only send). Enabling Auth automatically."
+      )
+    );
+  }
+
+  const templateDir = path.join(TEMPLATE_ROOT, answers.stack || "mern");
+  if (!(await fs.pathExists(templateDir))) {
+    console.error(chalk.red(`Error: template not found for stack "${answers.stack}".`));
+    process.exit(1);
+  }
+
+  await fs.copy(templateDir, appDir, {
+    filter: (src) => {
+      const base = path.basename(src);
+      if (base === "node_modules" || base === "dist") return false;
+      return true;
+    }
+  });
+
+  // Rename package.json names
+  await setRootPackageNameIfPresent(appDir, appName);
+  await setPackageName(path.join(appDir, "backend", "package.json"), `${appName}-backend`);
+
+  // Choose frontend template (vite by default)
+  if (answers.frontend === "next") {
+    await safeRemove(path.join(appDir, "frontend"));
+    await fs.copy(path.join(templateDir, "frontend-next"), path.join(appDir, "frontend"));
+  }
+
+  await setPackageName(path.join(appDir, "frontend", "package.json"), `${appName}-frontend`);
+
+  // Remove modules based on answers
+  if (!includeAuth) {
+    await safeRemove(path.join(appDir, "backend", "src", "modules", "auth"));
+    await safeRemove(path.join(appDir, "frontend", "src", "modules", "auth"));
+
+    // Patch backend app.js to remove auth routes import/mount
+    await replaceInFile(path.join(appDir, "backend", "src", "app.js"), [
+      { from: /^\s*import authRoutes.*\n/gm, to: "" },
+      { from: /^\s*app\.use\(["']\/api\/auth["'],\s*authRoutes\);\s*\n/gm, to: "" }
+    ]);
+
+    // Patch frontend App.jsx to remove auth-protected routing and auth imports
+    await replaceInFile(path.join(appDir, "frontend", "src", "App.jsx"), [
+      { from: /^\s*import\s+\{\s*ProtectedRoute\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*LoginPage\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*RegisterPage\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*VerifyEmailPage\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*ForgotPasswordPage\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*ResetPasswordPage\s*\}.*\n/gm, to: "" },
+      { from: /^\s*import\s+\{\s*useAuthStore\s*\}.*\n/gm, to: "" },
+      {
+        from: /<Route\s+path="\/"\s+element=\{\s*<ProtectedRoute>[\s\S]*?<\/ProtectedRoute>\s*\}\s*\/>\s*/m,
+        to: `<Route path="/" element={<DashboardPage />} />\n`
+      },
+      { from: /^\s*<Route path="\/login"[\s\S]*?\n/gm, to: "" },
+      { from: /^\s*<Route path="\/register"[\s\S]*?\n/gm, to: "" },
+      { from: /^\s*<Route path="\/verify-email"[\s\S]*?\n/gm, to: "" },
+      { from: /^\s*<Route path="\/forgot-password"[\s\S]*?\n/gm, to: "" },
+      { from: /^\s*<Route path="\/reset-password"[\s\S]*?\n/gm, to: "" },
+      { from: /const refreshMe[\s\S]*?;\n\n/m, to: "" },
+      { from: /const token[\s\S]*?;\n/m, to: "" },
+      { from: /const user[\s\S]*?;\n/m, to: "" },
+      { from: /useEffect\(\(\)\s*=>\s*\{\s*refreshMe\(\)[\s\S]*?\}\s*,\s*\[refreshMe\]\s*\);\s*\n/m, to: "" },
+      { from: /useEffect\(\(\)\s*=>\s*\{\s*if\s*\(token[\s\S]*?\}\s*,\s*\[token,\s*user\]\s*\);\s*\n/m, to: "" },
+      {
+        from: /{!token\s*\?\s*\([\s\S]*?\)\s*:\s*\([\s\S]*?\)\s*}/m,
+        to: `<span style={{ color: "#6B7280", fontWeight: 700, fontSize: 13 }}>Welcome</span>`
+      }
+    ]);
+  }
+  if (!includeEmail) {
+    await safeRemove(path.join(appDir, "backend", "src", "modules", "email"));
+
+    // Patch backend app.js to remove email routes import/mount
+    await replaceInFile(path.join(appDir, "backend", "src", "app.js"), [
+      { from: /^\s*import emailRoutes.*\n/gm, to: "" },
+      { from: /^\s*app\.use\(["']\/api\/email["'],\s*emailRoutes\);\s*\n/gm, to: "" }
+    ]);
+
+    // Patch auth.service.js to remove email-service dependency
+    await replaceInFile(
+      path.join(appDir, "backend", "src", "modules", "auth", "auth.service.js"),
+      [
+        {
+          from: /^\s*import\s+\{\s*[\s\S]*?\s*\}\s*from\s*"\.\.\/email\/email\.service\.js";\s*\n/gm,
+          to: ""
+        },
+        { from: /^\s*await\s+sendWelcomeEmail\([\s\S]*?\);\s*\n/gm, to: "" },
+        { from: /^\s*await\s+sendVerifyEmail\([\s\S]*?\);\s*\n/gm, to: "" },
+        { from: /^\s*await\s+sendPasswordResetEmail\([\s\S]*?\);\s*\n/gm, to: "" }
+      ]
+    );
+  }
+
+  // If docker enabled, generate docker-compose.yml
+  if (includeDocker) {
+    await generateDockerCompose({ appDir });
+  }
+
+  renderNextSteps({ appName, appDir, includeDocker });
+};
+
+main().catch((err) => {
+  console.error(chalk.red("Unexpected error:"), err?.message || err);
+  process.exit(1);
+});
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@surajprasad/create-starterkit",
+  "version": "0.1.0",
+  "description": "Create a production-ready Starterkit (MERN) with optional auth, email, and Docker.",
+  "type": "module",
+  "bin": {
+    "starterkit": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "keywords": [
+    "create",
+    "starterkit",
+    "cli",
+    "mern",
+    "scaffold"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "fs-extra": "^11.3.0",
+    "prompts": "^2.4.2"
+  }
+}

package/templates/mern/backend/.env.example

@@ -0,0 +1,11 @@
+PORT=5000
+NODE_ENV=development
+MONGO_URI=mongodb://localhost:27017/myapp
+JWT_SECRET=your_jwt_secret_here
+JWT_EXPIRES_IN=7d
+FRONTEND_URL=http://localhost:5173
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=your_email@gmail.com
+SMTP_PASS=your_app_password
+EMAIL_FROM=Your App <your_email@gmail.com>

package/templates/mern/backend/Dockerfile

@@ -0,0 +1,13 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install --omit=dev
+
+COPY . .
+
+EXPOSE 5000
+
+CMD ["node", "server.js"]
+

package/templates/mern/backend/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "starterkit-backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "dev": "node --watch server.js",
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
+    "express": "^4.21.2",
+    "helmet": "^7.1.0",
+    "joi": "^17.13.3",
+    "jsonwebtoken": "^9.0.2",
+    "mongoose": "^8.12.2",
+    "morgan": "^1.10.0",
+    "nodemailer": "^6.10.0"
+  }
+}

package/templates/mern/backend/server.js

@@ -0,0 +1,25 @@
+import { createServer } from "node:http";
+
+import app from "./src/app.js";
+import { connectDb } from "./src/config/db.js";
+import { loadEnv } from "./src/config/env.js";
+
+const start = async () => {
+  loadEnv();
+  await connectDb();
+
+  const port = Number(process.env.PORT || 5000);
+  const server = createServer(app);
+
+  server.listen(port, () => {
+    // eslint-disable-next-line no-console
+    console.log(`Backend listening on port ${port}`);
+  });
+};
+
+start().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error("Failed to start server:", err);
+  process.exit(1);
+});
+

package/templates/mern/backend/src/app.js

@@ -0,0 +1,48 @@
+import express from "express";
+import cors from "cors";
+import helmet from "helmet";
+import morgan from "morgan";
+
+import authRoutes from "./modules/auth/auth.routes.js";
+import emailRoutes from "./modules/email/email.routes.js";
+
+import { notFound } from "./middleware/notFound.middleware.js";
+import { errorMiddleware } from "./middleware/errorMiddleware.js";
+
+const app = express();
+
+app.use(helmet());
+const allowedOrigins = [
+  process.env.FRONTEND_URL,
+  "http://localhost:5173",
+  "http://127.0.0.1:5173"
+].filter(Boolean);
+
+const corsOptions = {
+  origin(origin, cb) {
+    if (!origin) return cb(null, true);
+    if (allowedOrigins.includes(origin)) return cb(null, true);
+    return cb(null, false);
+  },
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  allowedHeaders: ["Content-Type", "Authorization"]
+};
+
+app.use(cors(corsOptions));
+app.options("*", cors(corsOptions));
+app.use(express.json({ limit: "1mb" }));
+app.use(morgan("dev"));
+
+app.get("/health", (req, res) => {
+  res.json({ ok: true, timestamp: new Date().toISOString() });
+});
+
+app.use("/api/auth", authRoutes);
+app.use("/api/email", emailRoutes);
+
+app.use(notFound);
+app.use(errorMiddleware);
+
+export default app;
+

package/templates/mern/backend/src/config/db.js

@@ -0,0 +1,17 @@
+import mongoose from "mongoose";
+
+export const connectDb = async () => {
+  try {
+    const uri = process.env.MONGO_URI;
+    if (!uri) throw new Error("MONGO_URI is not set");
+
+    mongoose.set("strictQuery", true);
+    await mongoose.connect(uri);
+
+    // eslint-disable-next-line no-console
+    console.log("Connected to MongoDB");
+  } catch (err) {
+    throw err;
+  }
+};
+

package/templates/mern/backend/src/config/env.js

@@ -0,0 +1,38 @@
+import dotenv from "dotenv";
+import Joi from "joi";
+
+const envSchema = Joi.object({
+  PORT: Joi.number().port().default(5000),
+  NODE_ENV: Joi.string().valid("development", "production", "test").default("development"),
+  MONGO_URI: Joi.string().uri().required(),
+  JWT_SECRET: Joi.string().min(10).required(),
+  JWT_EXPIRES_IN: Joi.string().default("7d"),
+  FRONTEND_URL: Joi.string().uri().required(),
+  SMTP_HOST: Joi.string().required(),
+  SMTP_PORT: Joi.number().port().required(),
+  SMTP_USER: Joi.string().allow("").optional(),
+  SMTP_PASS: Joi.string().allow("").optional(),
+  EMAIL_FROM: Joi.string().required()
+}).unknown(true);
+
+export const loadEnv = () => {
+  dotenv.config();
+
+  const { error, value } = envSchema.validate(process.env, { abortEarly: true });
+  if (error) {
+    throw new Error(`Invalid environment variables: ${error.message}`);
+  }
+
+  process.env.PORT = String(value.PORT);
+  process.env.NODE_ENV = value.NODE_ENV;
+  process.env.MONGO_URI = value.MONGO_URI;
+  process.env.JWT_SECRET = value.JWT_SECRET;
+  process.env.JWT_EXPIRES_IN = value.JWT_EXPIRES_IN;
+  process.env.FRONTEND_URL = value.FRONTEND_URL;
+  process.env.SMTP_HOST = value.SMTP_HOST;
+  process.env.SMTP_PORT = String(value.SMTP_PORT);
+  process.env.SMTP_USER = value.SMTP_USER;
+  process.env.SMTP_PASS = value.SMTP_PASS;
+  process.env.EMAIL_FROM = value.EMAIL_FROM;
+};
+

package/templates/mern/backend/src/middleware/authMiddleware.js

@@ -0,0 +1,30 @@
+import { verifyToken } from "../utils/generateToken.util.js";
+import User from "../modules/auth/auth.model.js";
+
+export const authMiddleware = async (req, res, next) => {
+  try {
+    const header = req.headers.authorization || "";
+    const token = header.startsWith("Bearer ") ? header.slice(7) : null;
+
+    if (!token) {
+      const err = new Error("Unauthorized");
+      err.statusCode = 401;
+      throw err;
+    }
+
+    const decoded = verifyToken(token);
+    const user = await User.findById(decoded.userId).select("-password");
+    if (!user) {
+      const err = new Error("Unauthorized");
+      err.statusCode = 401;
+      throw err;
+    }
+
+    req.user = user;
+    next();
+  } catch (err) {
+    err.statusCode = err.statusCode || 401;
+    next(err);
+  }
+};
+

package/templates/mern/backend/src/middleware/errorMiddleware.js

@@ -0,0 +1,17 @@
+export const errorMiddleware = (err, req, res, next) => {
+  const status = Number(err?.statusCode || err?.status || 500);
+  const message = err?.message || "Internal Server Error";
+
+  if (process.env.NODE_ENV !== "test") {
+    // eslint-disable-next-line no-console
+    console.error(err);
+  }
+
+  res.status(status).json({
+    success: false,
+    message,
+    data: null,
+    timestamp: new Date().toISOString()
+  });
+};
+

package/templates/mern/backend/src/middleware/notFound.middleware.js

@@ -0,0 +1,9 @@
+export const notFound = (req, res) => {
+  res.status(404).json({
+    success: false,
+    message: `Route not found: ${req.method} ${req.originalUrl}`,
+    data: null,
+    timestamp: new Date().toISOString()
+  });
+};
+

package/templates/mern/backend/src/modules/auth/auth.controller.js

@@ -0,0 +1,45 @@
+import { asyncHandler } from "../../utils/asyncHandler.util.js";
+import { apiResponse } from "../../utils/apiResponse.util.js";
+import {
+  forgotPasswordService,
+  getMeService,
+  loginUser,
+  registerUser,
+  resetPasswordService,
+  verifyEmailService
+} from "./auth.service.js";
+
+export const register = asyncHandler(async (req, res) => {
+  const data = await registerUser(req.body);
+  res.status(201).json(apiResponse(true, "Registered successfully", data));
+});
+
+export const login = asyncHandler(async (req, res) => {
+  const data = await loginUser(req.body);
+  res.status(200).json(apiResponse(true, "Logged in successfully", data));
+});
+
+export const getMe = asyncHandler(async (req, res) => {
+  const data = await getMeService({ userId: req.user._id.toString() });
+  res.status(200).json(apiResponse(true, "Fetched profile", data));
+});
+
+export const verifyEmail = asyncHandler(async (req, res) => {
+  const { otp } = req.body;
+  const data = await verifyEmailService({ userId: req.user._id.toString(), otp });
+  res.status(200).json(apiResponse(true, "Email verified", data));
+});
+
+export const forgotPassword = asyncHandler(async (req, res) => {
+  const { email } = req.body;
+  const data = await forgotPasswordService({ email });
+  res.status(200).json(apiResponse(true, "If the email exists, a reset link was sent", data));
+});
+
+export const resetPassword = asyncHandler(async (req, res) => {
+  const { token } = req.query;
+  const { password } = req.body;
+  const data = await resetPasswordService({ rawToken: token, newPassword: password });
+  res.status(200).json(apiResponse(true, "Password reset successfully", data));
+});
+