better-ts-stack 2.0.2 → 2.1.1

package/dist/output/nextSteps.js

@@ -7,23 +7,16 @@ exports.generateNextSteps = generateNextSteps;
 const node_path_1 = __importDefault(require("node:path"));
 const node_process_1 = require("node:process");
 const MONGODB_AUTH_SETUP_URL = "https://better-ts-stack.abdullahtech.me/docs/modules/database#mongoose-and-mongodb";
-// Node 24 releases before 24.20 report mismatched file stats on Windows, which
-// makes srvx (TanStack's production server) reject every static asset
-const MIN_TANSTACK_WINDOWS_NODE = [24, 20];
-function isNodeBelow([major, minor]) {
-    const [currentMajor, currentMinor] = process.versions.node
-        .split(".")
-        .map(Number);
-    return (currentMajor < major || (currentMajor === major && currentMinor < minor));
-}
-// Generates a list of instructions for the user to follow after project creation
-function generateNextSteps(config, targetDir, depsInstalled) {
+// Generates a list of instructions for the user to follow after project
+// creation. The README version leaves out the cd step, which only makes
+// sense in the terminal
+function generateNextSteps(config, targetDir, depsInstalled, isForReadme = false) {
     const steps = [];
     const isFullstack = config.applicationType === "fullstack";
     // Step 1: cd into project directory, unless it was created in place
     // Quoted when it has spaces, so the command can be pasted as it is
     const relativeDir = node_path_1.default.relative((0, node_process_1.cwd)(), targetDir);
-    if (relativeDir) {
+    if (relativeDir && !isForReadme) {
         steps.push(/\s/.test(relativeDir) ? `cd "${relativeDir}"` : `cd ${relativeDir}`);
     }
     // Step 2: Set environment variables
@@ -35,17 +28,19 @@ function generateNextSteps(config, targetDir, depsInstalled) {
             ? "Review BETTER_AUTH_SECRET and BETTER_AUTH_URL in .env"
             : "Review the generated JWT_SECRET in .env");
     }
-    if (config.framework === "tanstack" &&
-        process.platform === "win32" &&
-        isNodeBelow(MIN_TANSTACK_WINDOWS_NODE)) {
-        steps.push(`Upgrade Node.js to ${MIN_TANSTACK_WINDOWS_NODE.join(".")} or newer: on Windows, ` +
-            `Node ${process.versions.node} makes "npm start" return 404 for CSS, JS, and other static files`);
-    }
     // Step 3: Install dependencies if not already done
     if (!depsInstalled) {
         steps.push(`${config.packageManager} install`);
     }
-    // Step 4: Database-specific steps
+    // Step 4: Database-specific steps. With Docker, Compose runs the database
+    const hasDockerDatabase = config.useDocker && config.database !== "none";
+    if (hasDockerDatabase) {
+        steps.push("docker compose up -d db");
+    }
+    if ((config.database === "prisma" || config.database === "drizzle") &&
+        !hasDockerDatabase) {
+        steps.push("Ensure PostgreSQL is running locally or update DATABASE_URL in .env");
+    }
     if (config.database === "prisma") {
         steps.push(`${config.packageManager} run prisma:generate`);
         steps.push(`${config.packageManager} run prisma:migrate`);
@@ -55,9 +50,12 @@ function generateNextSteps(config, targetDir, depsInstalled) {
         steps.push(`${config.packageManager} run db:migrate`);
     }
     else if (config.database === "mongoose") {
-        steps.push("Ensure MongoDB is running locally or update MONGODB_URI in .env");
-        // Better Auth's MongoDB adapter uses transactions, which need a replica set
-        if (config.useAuth && isFullstack) {
+        if (!hasDockerDatabase) {
+            steps.push("Ensure MongoDB is running locally or update MONGODB_URI in .env");
+        }
+        // Better Auth's MongoDB adapter uses transactions, which need a replica
+        // set; the Compose database already runs as one
+        if (config.useAuth && isFullstack && !hasDockerDatabase) {
             steps.push("Better Auth uses MongoDB transactions: run MongoDB as a replica set (or use Atlas) " +
                 'and create the "user", "session", "account", and "verification" collections before signing up. ' +
                 `See ${MONGODB_AUTH_SETUP_URL}`);
@@ -70,5 +68,8 @@ function generateNextSteps(config, targetDir, depsInstalled) {
             ? "Visit /sign-up to create your first account"
             : "Create a user via POST /auth/register then login with /auth/login");
     }
+    if (config.useDocker) {
+        steps.push(`To run the app in Docker instead: ${config.packageManager} run docker:up`);
+    }
     return steps;
 }

package/dist/prompts/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.collectStackChoices = void 0;
+exports.detectPackageManager = exports.collectStackChoices = void 0;
 exports.collectProjectPath = collectProjectPath;
 exports.confirmBuild = confirmBuild;
 const types_1 = require("../types");
@@ -9,6 +9,7 @@ const validators_1 = require("../validators");
 const stack_1 = require("./stack");
 var stack_2 = require("./stack");
 Object.defineProperty(exports, "collectStackChoices", { enumerable: true, get: function () { return stack_2.collectStackChoices; } });
+Object.defineProperty(exports, "detectPackageManager", { enumerable: true, get: function () { return stack_2.detectPackageManager; } });
 // Returns the project path from the command line, or asks for it
 async function collectProjectPath(preset, isNonInteractive) {
     if (preset !== undefined) {
@@ -22,13 +23,15 @@ async function collectProjectPath(preset, isNonInteractive) {
     return (0, stack_1.ask)(preset, () => (0, ui_1.text)({
         message: "Project name",
         placeholder: "my-awesome-project",
-        validate: (value) => (0, validators_1.validateProjectPath)(value ?? ""),
+        // An empty path would resolve to the current directory and pass
+        validate: (value) => value ? (0, validators_1.validateProjectPath)(value) : "Project name is required",
     }));
 }
 // Asks for final confirmation before building; declining ends the session
 async function confirmBuild() {
     const shouldBuild = await (0, stack_1.ask)(undefined, () => (0, ui_1.confirm)({ message: "Create this project?", initialValue: true }));
     if (!shouldBuild) {
+        (0, ui_1.info)("Nothing was created.");
         process.exit(0);
     }
 }

package/dist/prompts/stack.js

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectPackageManager = detectPackageManager;
 exports.ask = ask;
 exports.collectStackChoices = collectStackChoices;
 const core_1 = require("@clack/core");
 const types_1 = require("../types");
 const ui_1 = require("../ui");
+// The package manager that started the CLI (pnpm dlx, bunx, npx), from the
+// user agent it passes to the process; npm when it cannot be told
+function detectPackageManager() {
+    const userAgent = process.env.npm_config_user_agent ?? "";
+    const name = userAgent.split("/")[0];
+    return types_1.packageManagerOptions.some((option) => option.value === name)
+        ? name
+        : "npm";
+}
 // Returns the preset value when there is one, otherwise asks the user
 async function ask(preset, prompt) {
     if (preset !== undefined)
@@ -16,7 +26,8 @@ async function ask(preset, prompt) {
     const answer = await prompt();
     if ((0, core_1.isCancel)(answer)) {
         (0, ui_1.info)("Cancelled. Nothing was created.");
-        process.exit(0);
+        // 130 is the usual exit code for a run stopped with Ctrl+C
+        process.exit(130);
     }
     return answer;
 }
@@ -62,7 +73,7 @@ async function collectStackChoices(preset) {
     const packageManager = await ask(preset.packageManager, () => (0, ui_1.select)({
         message: "Package manager",
         options: types_1.packageManagerOptions,
-        initialValue: "npm",
+        initialValue: detectPackageManager(),
     }));
     const useDocker = await ask(preset.useDocker, () => (0, ui_1.confirm)({ message: "Add Docker?", initialValue: false }));
     // Better Auth stores users and sessions, so full-stack auth needs a database
@@ -77,6 +88,14 @@ async function collectStackChoices(preset) {
             initialValue: false,
         }))
         : false;
+    // Better Auth limits its own endpoints, so only the backends offer this
+    if (preset.useRateLimit && isFullstack) {
+        throw (0, types_1.buildError)(`Rate limiting is available for Express and NestJS. Better Auth in ${framework} already limits its own endpoints`, "INVALID_ARGUMENT");
+    }
+    const useRateLimit = isFullstack
+        ? false
+        : await ask(preset.useRateLimit, () => (0, ui_1.confirm)({ message: "Add rate limiting?", initialValue: false }));
+    const useCi = await ask(preset.useCi, () => (0, ui_1.confirm)({ message: "Add GitHub Actions CI?", initialValue: false }));
     const initGit = await ask(preset.initGit, () => (0, ui_1.confirm)({ message: "Initialize a git repository?", initialValue: true }));
     const installDeps = await ask(preset.installDeps, () => (0, ui_1.confirm)({ message: "Install dependencies now?", initialValue: false }));
     return {
@@ -85,6 +104,8 @@ async function collectStackChoices(preset) {
         packageManager,
         useDocker,
         useAuth,
+        useRateLimit,
+        useCi,
         initGit,
         installDeps,
     };

package/dist/types/index.js

@@ -11,6 +11,8 @@ exports.DEFAULT_CHOICES = {
     database: "none",
     useDocker: false,
     useAuth: false,
+    useRateLimit: false,
+    useCi: false,
     packageManager: "npm",
     initGit: true,
     installDeps: false,

package/dist/ui/messages.js

@@ -73,7 +73,9 @@ function showSummary(config, targetDir) {
         config.framework,
         config.database !== "none" && config.database,
         config.useAuth && "auth",
+        config.useRateLimit && "rate limit",
         config.useDocker && "docker",
+        config.useCi && "ci",
     ];
     const setup = [
         config.packageManager,
@@ -115,7 +117,7 @@ function showNextSteps(steps) {
     write();
     write(`  ${(0, theme_1.amber)((0, theme_1.bold)("Next steps"))}`);
     steps.forEach((step, index) => {
-        const isCommand = /^(cd|npm|pnpm|bun) /.test(step);
+        const isCommand = /^(cd|npm|pnpm|bun|docker) /.test(step);
         write(`  ${(0, theme_1.dim)(`${index + 1}.`)} ${isCommand ? (0, theme_1.lime)(step) : step}`);
     });
     write();

package/dist/validators/index.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.projectNameSchema = void 0;
+exports.PRESERVED_ENTRIES = exports.projectNameSchema = void 0;
 exports.validateProjectName = validateProjectName;
 exports.validateProjectPath = validateProjectPath;
 exports.validateDirectoryEmpty = validateDirectoryEmpty;
@@ -32,6 +32,9 @@ function validateProjectName(name) {
 function validateProjectPath(projectPath) {
     return validateProjectName(node_path_1.default.basename(node_path_1.default.resolve(projectPath)));
 }
+// Entries a project folder may already have: a repository cloned from an
+// empty remote, and files the operating system creates
+exports.PRESERVED_ENTRIES = [".git", ".DS_Store", "Thumbs.db"];
 // Ensures a directory is empty or does not exist before starting build
 async function validateDirectoryEmpty(dirPath) {
     const exists = await fs_extra_1.default.pathExists(dirPath);
@@ -42,7 +45,7 @@ async function validateDirectoryEmpty(dirPath) {
         return `Path "${dirPath}" exists but is not a directory`;
     }
     const files = await fs_extra_1.default.readdir(dirPath);
-    if (files.length === 0)
+    if (files.every((file) => exports.PRESERVED_ENTRIES.includes(file)))
         return null;
     return `Directory "${node_path_1.default.basename(dirPath)}" already exists and is not empty`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-ts-stack",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "A CLI that scaffolds Express, NestJS, Next.js, and TanStack Start projects with a database, authentication, and Docker already set up.",
   "keywords": [
     "cli",
@@ -51,8 +51,8 @@
   "dependencies": {
     "@clack/core": "^1.4.3",
     "fs-extra": "^11.4.0",
-    "handlebars": "^4.7.9",
-    "zod": "^4.5.4"
+    "handlebars": "^4.7.10",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@better-ts-stack/eslint-config": "*",

package/templates/backend/express/config.json

@@ -1,40 +1,42 @@
-{
-  "id": "express",
-  "name": "Express Base",
-  "description": "Base Express server with TypeScript, security headers, and a health check",
-  "type": "base",
-  "scripts": {
-    "dev": "cross-env NODE_ENV=development {{#if (eq packageManager 'bun')}}bun --watch src/index.ts{{else}}tsx watch src/index.ts{{/if}}",
-    "build": "tsc",
-    "start": "cross-env NODE_ENV=production {{runner}} dist/index.js",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "type:check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "express": "^5.2.1",
-    "dotenv": "^17.4.2",
-    "cors": "^2.8.6",
-    "cross-env": "^10.1.0",
-    "helmet": "^8.3.0",
-    "morgan": "^1.12.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^5.0.6",
-    "@types/morgan": "^1.9.10",
-    "@types/node": "^24.13.3",
-    "eslint": "^10.10.0",
-    "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.9.6",
-    "tsx": "^4.23.13",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0"
-  },
-  "envVars": {
-    "PORT": "3000"
-  }
-}
+{
+  "id": "express",
+  "name": "Express Base",
+  "description": "Base Express server with TypeScript, security headers, and a health check",
+  "type": "base",
+  "scripts": {
+    "dev": "cross-env NODE_ENV=development {{#if (eq packageManager 'bun')}}bun --watch src/index.ts{{else}}tsx watch src/index.ts{{/if}}",
+    "build": "tsc",
+    "start": "cross-env NODE_ENV=production {{runner}} dist/index.js",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "type:check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "express": "^5.3.0",
+    "dotenv": "^17.4.2",
+    "cors": "^2.8.6",
+    "cross-env": "^10.1.0",
+    "helmet": "^8.3.0",
+    "morgan": "^1.12.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/morgan": "^1.9.10",
+    "@types/node": "^24.19.2",
+    "eslint": "^10.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.10",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1"
+  },
+  "envVars": {
+    "PORT": "3000",
+    "CORS_ORIGIN": "*"
+  }
+}

package/templates/backend/express/gitignore

@@ -34,3 +34,6 @@ coverage/
 
 # Misc
 *.tsbuildinfo
+
+# Prisma client, created by prisma generate
+src/generated/

package/templates/backend/express/src/env.ts.hbs

@@ -0,0 +1,39 @@
+import "dotenv/config";
+import { z } from "zod";
+
+// Checked once at startup, so a missing or malformed variable stops the server
+// with a clear message instead of failing on the first request that needs it
+const envSchema = z.object({
+  PORT: z.coerce.number().int().positive().default(3000),
+  // "*" allows every origin; otherwise a comma-separated list of origins
+  CORS_ORIGIN: z
+    .string()
+    .default("*")
+    .transform((value) =>
+      value === "*" ? value : value.split(",").map((origin) => origin.trim())
+    ),
+{{#if (eq database 'prisma')}}
+  DATABASE_URL: z.url(),
+{{/if}}
+{{#if (eq database 'drizzle')}}
+  DATABASE_URL: z.url(),
+{{/if}}
+{{#if (eq database 'mongoose')}}
+  MONGODB_URI: z.url(),
+{{/if}}
+{{#if useAuth}}
+  JWT_SECRET: z.string().min(32, "JWT_SECRET must be at least 32 characters"),
+  JWT_EXPIRES_IN: z.string().default("1h"),
+{{/if}}
+});
+
+const result = envSchema.safeParse(process.env);
+
+if (!result.success) {
+  console.error(
+    `Invalid environment variables:\n${z.prettifyError(result.error)}`
+  );
+  process.exit(1);
+}
+
+export const env = result.data;

package/templates/backend/express/src/index.ts.hbs

@@ -1,75 +1,111 @@
-import "dotenv/config";
-import express, { Express, Request, Response, NextFunction } from "express";
-import cors from "cors";
-import helmet from "helmet";
-import morgan from "morgan";
-{{#if (eq database 'mongoose')}}
-import { connectDB } from "./lib/db";
-{{/if}}
-import healthRouter from "./routes/health";
-{{#if useAuth}}
-import authRouter from "./routes/auth";
-{{/if}}
-
-const app: Express = express();
-const port = process.env.PORT || 3000;
-
-// Middleware
-app.use(helmet());
-app.use(cors());
-app.use(morgan("dev"));
-app.use(express.json());
-app.use(express.urlencoded({ extended: true }));
-
-// Routes
-app.use("/health", healthRouter);
-{{#if useAuth}}
-app.use("/auth", authRouter);
-{{/if}}
-
-// 404 handler
-app.use((_req: Request, res: Response) => {
-  res.status(404).json({ error: "Not Found" });
-});
-
-// Error handler
-app.use(
-  (
-    err: Error & { status?: number; statusCode?: number; expose?: boolean },
-    _req: Request,
-    res: Response,
-    _next: NextFunction,
-  ) => {
-    // Middleware such as express.json() sets 4xx statuses (bad JSON, body too large)
-    const status = err.status ?? err.statusCode ?? 500;
-
-    if (status >= 400 && status < 500) {
-      res.status(status).json({ error: err.expose ? err.message : "Bad Request" });
-      return;
-    }
-
-    console.error(err.stack);
-    res.status(500).json({ error: "Internal Server Error" });
-  },
-);
-
-function listen(): void {
-  app.listen(port, () => {
-    console.log(`Server is running on http://localhost:${port}
-    Health: http://localhost:${port}/health
-    `);
-  });
-}
-
-{{#if (eq database 'mongoose')}}
-void connectDB()
-  .then(listen)
-  .catch((error: unknown) => {
-    console.error(error);
-    process.exitCode = 1;
-  });
-{{else}}
-listen();
-{{/if}}
-
-export default app;
+import "dotenv/config";
+import express, { Express, Request, Response, NextFunction } from "express";
+import cors from "cors";
+import helmet from "helmet";
+import morgan from "morgan";
+import { env } from "./env";
+{{#if (eq database 'prisma')}}
+import { disconnectPrisma } from "./lib/prisma";
+{{/if}}
+{{#if (eq database 'drizzle')}}
+import { db } from "./lib/db";
+{{/if}}
+{{#if (eq database 'mongoose')}}
+import { connectDB, disconnectDB } from "./lib/db";
+{{/if}}
+{{#if useRateLimit}}
+import { apiLimiter } from "./middleware/rateLimit";
+{{/if}}
+import healthRouter from "./routes/health";
+{{#if useAuth}}
+import authRouter from "./routes/auth";
+{{/if}}
+
+const app: Express = express();
+const port = env.PORT;
+
+// Middleware
+app.use(helmet());
+app.use(cors({ origin: env.CORS_ORIGIN }));
+{{#if useRateLimit}}
+app.use(apiLimiter);
+{{/if}}
+app.use(morgan("dev"));
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+
+// Routes
+app.use("/health", healthRouter);
+{{#if useAuth}}
+app.use("/auth", authRouter);
+{{/if}}
+
+// 404 handler
+app.use((_req: Request, res: Response) => {
+  res.status(404).json({ error: "Not Found" });
+});
+
+// Error handler
+app.use(
+  (
+    err: Error & { status?: number; statusCode?: number; expose?: boolean },
+    _req: Request,
+    res: Response,
+    _next: NextFunction,
+  ) => {
+    // Middleware such as express.json() sets 4xx statuses (bad JSON, body too large)
+    const status = err.status ?? err.statusCode ?? 500;
+
+    if (status >= 400 && status < 500) {
+      res.status(status).json({ error: err.expose ? err.message : "Bad Request" });
+      return;
+    }
+
+    console.error(err.stack);
+    res.status(500).json({ error: "Internal Server Error" });
+  },
+);
+
+// Closes the database connection once the server has stopped
+function closeDatabase(): Promise<void> {
+{{#if (eq database 'prisma')}}
+  return disconnectPrisma();
+{{else if (eq database 'drizzle')}}
+  return db.$client.end();
+{{else if (eq database 'mongoose')}}
+  return disconnectDB();
+{{else}}
+  return Promise.resolve();
+{{/if}}
+}
+
+function listen(): void {
+  const server = app.listen(port, () => {
+    console.log(`Server is running on http://localhost:${port}
+    Health: http://localhost:${port}/health
+    `);
+  });
+
+  // Docker and most hosts stop the process with SIGTERM, and Ctrl+C sends
+  // SIGINT: finish open requests, close the database, then exit
+  const shutdown = () => {
+    server.close(() => {
+      void closeDatabase().finally(() => process.exit(0));
+    });
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+}
+
+{{#if (eq database 'mongoose')}}
+void connectDB()
+  .then(listen)
+  .catch((error: unknown) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+{{else}}
+listen();
+{{/if}}
+
+export default app;