better-ts-stack 2.1.0 → 2.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Abdullah
-
-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.
+MIT License
+
+Copyright (c) 2026 Abdullah
+
+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/dist/args.js

@@ -22,6 +22,9 @@ Options left out are asked interactively, unless --yes is given.
   --docker, --no-docker   Add Docker files
   --rate-limit, --no-rate-limit
                           Add rate limiting (Express and NestJS)
+  --ci, --no-ci           Add a GitHub Actions workflow
+  --agents, --no-agents   Add AGENTS.md for AI coding agents
+  --vscode, --no-vscode   Add VS Code settings and recommended extensions
   --git, --no-git         Initialize a git repository
   --install, --no-install Install dependencies
   -y, --yes               Use defaults for missing options and skip confirmation
@@ -56,6 +59,9 @@ function parseCliArgs(argv) {
                 auth: { type: "boolean" },
                 docker: { type: "boolean" },
                 "rate-limit": { type: "boolean" },
+                ci: { type: "boolean" },
+                agents: { type: "boolean" },
+                vscode: { type: "boolean" },
                 git: { type: "boolean" },
                 install: { type: "boolean" },
                 yes: { type: "boolean", short: "y" },
@@ -79,6 +85,9 @@ function parseCliArgs(argv) {
         useAuth: values.auth,
         useDocker: values.docker,
         useRateLimit: values["rate-limit"],
+        useCi: values.ci,
+        useAgents: values.agents,
+        useVscode: values.vscode,
         initGit: values.git,
         installDeps: values.install,
     };

package/dist/builder/configGenerator.js

@@ -136,7 +136,9 @@ async function generateEnvFile(targetDir, envVars) {
         let envContent = "# Environment Variables\n";
         envContent +=
             "# Copy this file to .env and update with your actual values\n\n";
-        let localEnvContent = envContent;
+        let localEnvContent = "# Environment Variables\n";
+        localEnvContent +=
+            "# Local values for this project. Do not commit them\n\n";
         // Add each environment variable
         for (const [key, value] of Object.entries(envVars)) {
             const resolvedValue = exports.GENERATED_SECRETS.includes(key)

package/dist/builder/moduleSelector.js

@@ -10,7 +10,8 @@ function selectModules(config) {
         : `frontend/${framework}`;
     const modules = [];
     // Database, auth, and rate-limit modules have one variant per framework
-    // (prisma/express, auth/nextjs, ...); the Docker module is shared
+    // (prisma/express, auth/nextjs, ...); the Docker, CI, and agents modules are
+    // shared
     if (config.database !== "none")
         modules.push(`${config.database}/${framework}`);
     if (config.useDocker)
@@ -19,5 +20,11 @@ function selectModules(config) {
         modules.push(`auth/${framework}`);
     if (config.useRateLimit)
         modules.push(`rate-limit/${framework}`);
+    if (config.useCi)
+        modules.push("ci");
+    if (config.useAgents)
+        modules.push("agents");
+    if (config.useVscode)
+        modules.push("vscode");
     return { base, modules };
 }

package/dist/builder/readmeGenerator.js

@@ -52,8 +52,20 @@ function renderReadme(config, mergedConfig, targetDir) {
             ? "- **Auth:** Better Auth with email and password"
             : "- **Auth:** JWT with `/auth/register`, `/auth/login`, and `/auth/me`");
     }
+    if (config.useRateLimit) {
+        lines.push(`- **Rate limiting:** 100 requests per client IP in 15 minutes${config.useAuth ? ", and 10 sign-up or login attempts" : ""}`);
+    }
     if (config.useDocker)
         lines.push("- **Docker:** Dockerfile and Compose file");
+    if (config.useCi) {
+        lines.push("- **CI:** GitHub Actions builds, type-checks, and lints every push to `main` and every pull request");
+    }
+    if (config.useVscode) {
+        lines.push("- **VS Code:** workspace settings and recommended extensions in `.vscode/`");
+    }
+    if (config.useAgents) {
+        lines.push("- **AI agents:** `AGENTS.md` describes the stack, commands, and rules for coding agents");
+    }
     lines.push(`- **Package manager:** ${config.packageManager}`, "");
     const steps = (0, nextSteps_1.generateNextSteps)(config, targetDir, false, true);
     lines.push("## Getting started", "", ...steps.map((step, index) => {

package/dist/builder/templateContext.js

@@ -31,6 +31,28 @@ const DOCKER_COMMANDS = {
         run: "bun run",
     },
 };
+// Placeholders for the CI build, the same ones the Dockerfile uses: a build
+// needs these to be set, but never connects to a database
+function getCiBuildEnv(config) {
+    const env = [];
+    if (config.database === "prisma" || config.database === "drizzle") {
+        env.push({
+            name: "DATABASE_URL",
+            value: "postgresql://postgres:postgres@localhost:5432/postgres",
+        });
+    }
+    if (config.database === "mongoose") {
+        env.push({ name: "MONGODB_URI", value: "mongodb://localhost:27017/build" });
+    }
+    // next build loads the auth route, which initializes Better Auth
+    if (config.framework === "nextjs" && config.useAuth) {
+        env.push({
+            name: "BETTER_AUTH_SECRET",
+            value: "build-only-placeholder-secret-not-used-at-runtime",
+        });
+    }
+    return env;
+}
 function buildTemplateContext(config) {
     return {
         projectName: config.projectName,
@@ -41,7 +63,9 @@ function buildTemplateContext(config) {
         useDocker: config.useDocker,
         useAuth: config.useAuth,
         useRateLimit: config.useRateLimit,
+        useCi: config.useCi,
         docker: DOCKER_COMMANDS[config.packageManager],
+        ciBuildEnv: getCiBuildEnv(config),
         helpers: {
             eq: (a, b) => a === b,
             runner: () => {

package/dist/output/nextSteps.js

@@ -37,6 +37,10 @@ function generateNextSteps(config, targetDir, depsInstalled, isForReadme = false
     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`);

package/dist/prompts/index.js

@@ -23,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

@@ -95,6 +95,12 @@ async function collectStackChoices(preset) {
     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 useAgents = await ask(preset.useAgents, () => (0, ui_1.confirm)({
+        message: "Add AGENTS.md for AI coding agents?",
+        initialValue: false,
+    }));
+    const useVscode = await ask(preset.useVscode, () => (0, ui_1.confirm)({ message: "Add VS Code settings?", 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 {
@@ -104,6 +110,9 @@ async function collectStackChoices(preset) {
         useDocker,
         useAuth,
         useRateLimit,
+        useCi,
+        useAgents,
+        useVscode,
         initGit,
         installDeps,
     };

package/dist/types/index.js

@@ -12,6 +12,9 @@ exports.DEFAULT_CHOICES = {
     useDocker: false,
     useAuth: false,
     useRateLimit: false,
+    useCi: false,
+    useAgents: false,
+    useVscode: false,
     packageManager: "npm",
     initGit: true,
     installDeps: false,

package/dist/ui/messages.js

@@ -75,6 +75,9 @@ function showSummary(config, targetDir) {
         config.useAuth && "auth",
         config.useRateLimit && "rate limit",
         config.useDocker && "docker",
+        config.useCi && "ci",
+        config.useAgents && "agents",
+        config.useVscode && "vscode",
     ];
     const setup = [
         config.packageManager,

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "better-ts-stack",
-  "version": "2.1.0",
-  "description": "A CLI that scaffolds Express, NestJS, Next.js, and TanStack Start projects with a database, authentication, and Docker already set up.",
-  "keywords": [
-    "cli",
-    "builder",
-    "backend",
-    "typescript",
-    "express",
-    "nestjs",
-    "nextjs",
-    "tanstack-start",
-    "prisma",
-    "drizzle",
-    "mongoose",
-    "template"
-  ],
-  "homepage": "https://better-ts-stack.abdullahtech.me",
-  "bugs": {
-    "url": "https://github.com/Abdullah-dev0/better-ts-stack/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Abdullah-dev0/better-ts-stack.git"
-  },
-  "license": "MIT",
-  "author": "Abdullah",
-  "type": "commonjs",
-  "main": "dist/index.js",
-  "bin": {
-    "better-ts-stack": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "templates"
-  ],
-  "scripts": {
-    "dev": "tsx  src/index.ts",
-    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "tsc",
-    "postbuild": "node -e \"const fs=require('fs');const p='dist/index.js';fs.writeFileSync(p,'#!/usr/bin/env node\\n'+fs.readFileSync(p,'utf8'))\"",
-    "prepack": "npm run build",
-    "start": "node dist/index.js",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
-    "format": "prettier --write  \"**/*.{ts,tsx,js,jsx,json,md,mdx,css}\"",
-    "format:check": "prettier --check  \"**/*.{ts,tsx,js,jsx,json,md,mdx,css}\"",
-    "type:check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@clack/core": "^1.4.3",
-    "fs-extra": "^11.4.0",
-    "handlebars": "^4.7.9",
-    "zod": "^4.5.4"
-  },
-  "devDependencies": {
-    "@better-ts-stack/eslint-config": "*",
-    "@better-ts-stack/prettier-config": "*",
-    "@types/fs-extra": "^11.0.4",
-    "@types/node": "^24.13.3",
-    "eslint": "^10.10.0",
-    "prettier": "^3.9.6",
-    "tsx": "^4.23.13",
-    "typescript": "^6.0.3"
-  },
-  "engines": {
-    "node": ">=24.0.0"
-  },
-  "prettier": "@better-ts-stack/prettier-config"
-}
+{
+  "name": "better-ts-stack",
+  "version": "2.1.2",
+  "description": "A CLI that scaffolds Express, NestJS, Next.js, and TanStack Start projects with a database, authentication, and Docker already set up.",
+  "keywords": [
+    "cli",
+    "builder",
+    "backend",
+    "typescript",
+    "express",
+    "nestjs",
+    "nextjs",
+    "tanstack-start",
+    "prisma",
+    "drizzle",
+    "mongoose",
+    "template"
+  ],
+  "homepage": "https://better-ts-stack.abdullahtech.me",
+  "bugs": {
+    "url": "https://github.com/Abdullah-dev0/better-ts-stack/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Abdullah-dev0/better-ts-stack.git"
+  },
+  "license": "MIT",
+  "author": "Abdullah",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "bin": {
+    "better-ts-stack": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "dev": "tsx  src/index.ts",
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "postbuild": "node -e \"const fs=require('fs');const p='dist/index.js';fs.writeFileSync(p,'#!/usr/bin/env node\\n'+fs.readFileSync(p,'utf8'))\"",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write  \"**/*.{ts,tsx,js,jsx,json,md,mdx,css}\"",
+    "format:check": "prettier --check  \"**/*.{ts,tsx,js,jsx,json,md,mdx,css}\"",
+    "type:check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/core": "^1.4.3",
+    "fs-extra": "^11.4.0",
+    "handlebars": "^4.7.10",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@better-ts-stack/eslint-config": "*",
+    "@better-ts-stack/prettier-config": "*",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.13.3",
+    "eslint": "^10.10.0",
+    "prettier": "^3.9.6",
+    "tsx": "^4.23.13",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "prettier": "@better-ts-stack/prettier-config"
+}

package/templates/backend/express/.prettierignore

@@ -1,52 +1,52 @@
-# Dependencies
-node_modules
-**/node_modules
-
-# Build outputs
-.next
-out
-dist
-build
-**/dist
-**/.next
-**/out
-**/build
-
-# Generated files
-*.min.js
-*.min.css
-coverage
-.nyc_output
-
-# Lock files
-package-lock.json
-yarn.lock
-pnpm-lock.yaml
-bun.lock
-
-# Logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-# Environment files
-.env
-.env.local
-.env.*.local
-
-# IDE
-.vscode
-.idea
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Templates (do not format generated/scaffold content)
-templates
-**/templates/**
-*.hbs
+# Dependencies
+node_modules
+**/node_modules
+
+# Build outputs
+.next
+out
+dist
+build
+**/dist
+**/.next
+**/out
+**/build
+
+# Generated files
+*.min.js
+*.min.css
+coverage
+.nyc_output
+
+# Lock files
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+bun.lock
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Templates (do not format generated/scaffold content)
+templates
+**/templates/**
+*.hbs

package/templates/backend/express/.prettierrc

@@ -1,16 +1,16 @@
-{
-  "semi": true,
-  "trailingComma": "es5",
-  "singleQuote": false,
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false,
-  "arrowParens": "always",
-  "endOfLine": "lf",
-  "plugins": ["@trivago/prettier-plugin-sort-imports"],
-  "importOrder": ["<THIRD_PARTY_MODULES>", "^[./]"],
-  "importOrderSeparation": true,
-  "importOrderSortSpecifiers": true,
-  "importOrderGroupNamespaceSpecifiers": true,
-  "importOrderCaseInsensitive": true
-}
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "plugins": ["@trivago/prettier-plugin-sort-imports"],
+  "importOrder": ["<THIRD_PARTY_MODULES>", "^[./]"],
+  "importOrderSeparation": true,
+  "importOrderSortSpecifiers": true,
+  "importOrderGroupNamespaceSpecifiers": true,
+  "importOrderCaseInsensitive": true
+}

package/templates/backend/express/config.json

@@ -13,13 +13,13 @@
     "type:check": "tsc --noEmit"
   },
   "dependencies": {
-    "express": "^5.2.1",
+    "express": "^5.3.0",
     "dotenv": "^17.4.2",
     "cors": "^2.8.6",
     "cross-env": "^10.1.0",
     "helmet": "^8.3.0",
-    "morgan": "^1.12.0",
-    "zod": "^4.6.5"
+    "morgan": "^1.12.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -27,13 +27,13 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/morgan": "^1.9.10",
-    "@types/node": "^24.13.3",
-    "eslint": "^10.10.0",
+    "@types/node": "^24.19.2",
+    "eslint": "^10.14.0",
     "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.9.6",
-    "tsx": "^4.23.13",
+    "prettier": "^3.9.10",
+    "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0"
+    "typescript-eslint": "^8.72.1"
   },
   "envVars": {
     "PORT": "3000",

package/templates/backend/express/gitignore

@@ -18,7 +18,9 @@ yarn-debug.log*
 yarn-error.log*
 
 # IDE
-.vscode/
+.vscode/*
+!.vscode/settings.json
+!.vscode/extensions.json
 .idea/
 *.swp
 *.swo
@@ -34,3 +36,6 @@ coverage/
 
 # Misc
 *.tsbuildinfo
+
+# Prisma client, created by prisma generate
+src/generated/

package/templates/backend/express/tsconfig.eslint.json

@@ -1,9 +1,9 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "allowJs": true,
-    "rootDir": "."
-  },
-  "include": ["src/**/*", "eslint.config.mjs", "prisma.config.ts"]
-}
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "allowJs": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*", "eslint.config.mjs", "prisma.config.ts"]
+}