better-ts-stack 1.1.4 → 2.0.1

package/templates/frontend/nextjs/config.json

@@ -1,38 +1,37 @@
-{
-  "id": "nextjs",
-  "name": "Next.js",
-  "description": "Next.js 16 App Router with TypeScript and Tailwind CSS",
-  "type": "base",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "eslint",
-    "type:check": "tsc --noEmit"
-  },
-  "dependencies": {
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.41.0",
-    "next": "^16.3.4",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "tailwind-merge": "^3.6.0",
-    "@radix-ui/react-slot": "^1.3.3"
-  },
-  "devDependencies": {
-    "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^24.13.3",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
-    "eslint": "^10.10.0",
-    "eslint-config-next": "^16.3.4",
-    "tailwindcss": "^4.3.3",
-    "typescript": "^6.0.3",
-    "@eslint/compat": "^2.1.1"
-  },
-  "envVars": {
-    "PORT": "3000"
-  },
-  "templateFiles": ["app/page.tsx.hbs", "proxy.ts.hbs", "next.config.ts.hbs"]
-}
+{
+  "id": "nextjs",
+  "name": "Next.js",
+  "description": "Next.js 16 App Router with TypeScript and Tailwind CSS",
+  "type": "base",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "type:check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.41.0",
+    "next": "^16.3.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tailwind-merge": "^3.6.0",
+    "@radix-ui/react-slot": "^1.3.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "eslint": "^10.10.0",
+    "eslint-config-next": "^16.3.4",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3",
+    "@eslint/compat": "^2.1.1"
+  },
+  "envVars": {
+    "PORT": "3000"
+  }
+}

package/templates/frontend/nextjs/eslint.config.mjs

@@ -1,11 +1,11 @@
-import { fixupConfigRules } from "@eslint/compat";
-import nextVitals from "eslint-config-next/core-web-vitals";
-import nextTs from "eslint-config-next/typescript";
-import { defineConfig, globalIgnores } from "eslint/config";
-
-const eslintConfig = defineConfig([
-  ...fixupConfigRules([...nextVitals, ...nextTs]),
-  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
-]);
-
-export default eslintConfig;
+import { fixupConfigRules } from "@eslint/compat";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+const eslintConfig = defineConfig([
+  ...fixupConfigRules([...nextVitals, ...nextTs]),
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);
+
+export default eslintConfig;

package/templates/frontend/nextjs/next.config.ts.hbs

@@ -1,12 +1,12 @@
-import type { NextConfig } from "next";
-
-{{#if useDocker}}
-const nextConfig: NextConfig = {
-  // Standalone output is what the Docker image runs (node server.js)
-  output: "standalone",
-};
-{{else}}
-const nextConfig: NextConfig = {};
-{{/if}}
-
-export default nextConfig;
+import type { NextConfig } from "next";
+
+{{#if useDocker}}
+const nextConfig: NextConfig = {
+  // Standalone output is what the Docker image runs (node server.js)
+  output: "standalone",
+};
+{{else}}
+const nextConfig: NextConfig = {};
+{{/if}}
+
+export default nextConfig;

package/templates/frontend/tanstack/config.json

@@ -1,48 +1,45 @@
-{
-  "id": "tanstack",
-  "name": "TanStack Start",
-  "description": "TanStack Start with TanStack Router, React 19, and Tailwind CSS v4",
-  "type": "base",
-  "scripts": {
-    "dev": "vite dev",
-    "build": "vite build",
-    "start": "srvx --prod -s ../client dist/server/server.js",
-    "preview": "vite preview",
-    "type:check": "tsc --noEmit",
-    "lint": "eslint src"
-  },
-  "dependencies": {
-    "@tanstack/react-query": "^5.102.8",
-    "@tanstack/react-query-devtools": "^5.102.8",
-    "@tanstack/react-router": "^1.170.36",
-    "@tanstack/react-router-devtools": "^1.167.2",
-    "@tanstack/react-router-ssr-query": "^1.167.2",
-    "@tanstack/react-start": "^1.168.53",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.41.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "srvx": "^1.0.4",
-    "tailwind-merge": "^3.6.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^24.13.3",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
-    "@vitejs/plugin-react": "^6.1.1",
-    "eslint": "^10.10.0",
-    "tailwindcss": "^4.3.3",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0",
-    "vite": "^8.3.0"
-  },
-  "envVars": {
-    "PORT": "3000"
-  },
-  "templateFiles": [
-    "src/routes/index.tsx.hbs"
-  ]
-}
+{
+  "id": "tanstack",
+  "name": "TanStack Start",
+  "description": "TanStack Start with TanStack Router, React 19, and Tailwind CSS v4",
+  "type": "base",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "start": "srvx --prod -s ../client dist/server/server.js",
+    "preview": "vite preview",
+    "type:check": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.102.8",
+    "@tanstack/react-query-devtools": "^5.102.8",
+    "@tanstack/react-router": "^1.170.36",
+    "@tanstack/react-router-devtools": "^1.167.2",
+    "@tanstack/react-router-ssr-query": "^1.167.2",
+    "@tanstack/react-start": "^1.168.53",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.41.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "srvx": "^1.0.4",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "eslint": "^10.10.0",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.69.0",
+    "vite": "^8.3.0"
+  },
+  "envVars": {
+    "PORT": "3000"
+  }
+}

package/templates/modules/auth/express/config.json

@@ -1,26 +1,20 @@
-{
-  "id": "auth",
-  "name": "JWT Auth",
-  "description": "JWT authentication with bcrypt password hashing",
-  "type": "feature",
-  "dependencies": {
-    "bcrypt": "^6.0.0",
-    "jsonwebtoken": "^9.0.3"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/jsonwebtoken": "^9.0.10"
-  },
-  "scripts": {},
-  "envVars": {
-    "JWT_SECRET": "please-change-me",
-    "JWT_EXPIRES_IN": "1h"
-  },
-  "templateFiles": [
-    "src/lib/jwt.ts.hbs",
-    "src/middleware/requireAuth.ts.hbs",
-    "src/services/userStore.ts.hbs",
-    "src/routes/auth.ts.hbs",
-    "src/controllers/authController.ts.hbs"
-  ]
-}
+{
+  "id": "auth",
+  "name": "JWT Auth",
+  "description": "JWT authentication with bcrypt password hashing",
+  "type": "feature",
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "^6.0.0",
+    "@types/jsonwebtoken": "^9.0.10"
+  },
+  "scripts": {},
+  "envVars": {
+    "JWT_SECRET": "please-change-me",
+    "JWT_EXPIRES_IN": "1h"
+  }
+}

package/templates/modules/auth/express/src/controllers/authController.ts.hbs

@@ -1,5 +1,6 @@
 import { Request, Response } from "express";
 import bcrypt from "bcrypt";
+import { z } from "zod";
 import { signToken } from "../lib/jwt";
 import { AuthenticatedRequest } from "../middleware/requireAuth";
 import {
@@ -14,54 +15,47 @@ const MIN_PASSWORD_LENGTH = 8;
 // bcrypt ignores bytes beyond 72, so longer passwords would be silently truncated
 const MAX_PASSWORD_BYTES = 72;
 
-// Request bodies are untrusted JSON, so fields may have any type
-interface RegisterBody {
-  email?: unknown;
-  password?: unknown;
-  name?: unknown;
-}
-
-interface LoginBody {
-  email?: unknown;
-  password?: unknown;
-}
-
-// Returns a trimmed, lowercased email, or null when the value is not a usable string
-function normalizeEmail(email: unknown): string | null {
-  if (typeof email !== "string") return null;
-  const normalized = email.trim().toLowerCase();
-  return normalized || null;
-}
-
-export async function register(
-  req: Request<object, unknown, RegisterBody | undefined>,
-  res: Response,
-): Promise<void> {
+// Emails are trimmed and lowercased so sign-in is case-insensitive
+const emailSchema = z
+  .string("Email and password are required")
+  .trim()
+  .toLowerCase()
+  .pipe(z.email("Email must be a valid email address"));
+
+const registerSchema = z.object({
+  email: emailSchema,
+  password: z
+    .string("Email and password are required")
+    .min(
+      MIN_PASSWORD_LENGTH,
+      `Password must be at least ${MIN_PASSWORD_LENGTH} characters`,
+    )
+    .refine(
+      (password) => Buffer.byteLength(password, "utf8") <= MAX_PASSWORD_BYTES,
+      `Password must be at most ${MAX_PASSWORD_BYTES} bytes`,
+    ),
+  name: z.string("Name must be a string").nullish(),
+});
+
+const loginSchema = z.object({
+  email: emailSchema,
+  password: z.string("Email and password are required").min(1),
+});
+
+// Sends a 400 with the first validation message and returns null when the body is invalid
+function parseBody<T>(schema: z.ZodType<T>, req: Request, res: Response): T | null {
   // Express 5 leaves req.body undefined when the request has no body
-  const body = req.body ?? {};
-  const email = normalizeEmail(body.email);
-  const password = body.password;
-  const name = body.name ?? null;
-
-  if (!email || typeof password !== "string" || !password) {
-    res.status(400).json({ error: "Email and password are required" });
-    return;
-  }
+  const result = schema.safeParse(req.body ?? {});
+  if (result.success) return result.data;
 
-  if (
-    password.length < MIN_PASSWORD_LENGTH ||
-    Buffer.byteLength(password, "utf8") > MAX_PASSWORD_BYTES
-  ) {
-    res.status(400).json({
-      error: `Password must be at least ${MIN_PASSWORD_LENGTH} characters and at most ${MAX_PASSWORD_BYTES} bytes`,
-    });
-    return;
-  }
+  res.status(400).json({ error: result.error.issues[0].message });
+  return null;
+}
 
-  if (name !== null && typeof name !== "string") {
-    res.status(400).json({ error: "Name must be a string" });
-    return;
-  }
+export async function register(req: Request, res: Response): Promise<void> {
+  const body = parseBody(registerSchema, req, res);
+  if (!body) return;
+  const { email, password, name = null } = body;
 
   const existingUser = await findUserByEmail(email);
   if (existingUser) {
@@ -88,18 +82,10 @@ export async function register(
   res.status(201).json({ user: toPublicUser(user), token });
 }
 
-export async function login(
-  req: Request<object, unknown, LoginBody | undefined>,
-  res: Response,
-): Promise<void> {
-  const body = req.body ?? {};
-  const email = normalizeEmail(body.email);
-  const password = body.password;
-
-  if (!email || typeof password !== "string" || !password) {
-    res.status(400).json({ error: "Email and password are required" });
-    return;
-  }
+export async function login(req: Request, res: Response): Promise<void> {
+  const body = parseBody(loginSchema, req, res);
+  if (!body) return;
+  const { email, password } = body;
 
   const user = await findUserByEmail(email);
 

package/templates/modules/auth/nestjs/config.json

@@ -0,0 +1,20 @@
+{
+  "id": "auth",
+  "name": "JWT Auth",
+  "description": "JWT authentication for NestJS with bcrypt password hashing",
+  "type": "feature",
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "jsonwebtoken": "^9.0.3",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "^6.0.0",
+    "@types/jsonwebtoken": "^9.0.10"
+  },
+  "scripts": {},
+  "envVars": {
+    "JWT_SECRET": "please-change-me",
+    "JWT_EXPIRES_IN": "1h"
+  }
+}

package/templates/modules/auth/nestjs/src/auth/auth.controller.ts

@@ -0,0 +1,46 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Post,
+  Req,
+  UseGuards,
+} from "@nestjs/common";
+
+import { type AuthenticatedRequest, AuthGuard } from "./auth.guard.js";
+import {
+  type LoginInput,
+  loginSchema,
+  type RegisterInput,
+  registerSchema,
+} from "./auth.schemas.js";
+import { type AuthResponse, AuthService } from "./auth.service.js";
+import type { AuthTokenPayload } from "./jwt.js";
+import { ZodValidationPipe } from "./zod-validation.pipe.js";
+
+@Controller("auth")
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Post("register")
+  register(
+    @Body(new ZodValidationPipe(registerSchema)) body: RegisterInput
+  ): Promise<AuthResponse> {
+    return this.authService.register(body);
+  }
+
+  @Post("login")
+  @HttpCode(200)
+  login(
+    @Body(new ZodValidationPipe(loginSchema)) body: LoginInput
+  ): Promise<AuthResponse> {
+    return this.authService.login(body);
+  }
+
+  @Get("me")
+  @UseGuards(AuthGuard)
+  me(@Req() request: AuthenticatedRequest): { user?: AuthTokenPayload } {
+    return { user: request.user };
+  }
+}

package/templates/modules/auth/nestjs/src/auth/auth.guard.ts

@@ -0,0 +1,36 @@
+import {
+  type CanActivate,
+  type ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from "@nestjs/common";
+import type { Request } from "express";
+
+import { type AuthTokenPayload, verifyToken } from "./jwt.js";
+
+export interface AuthenticatedRequest extends Request {
+  user?: AuthTokenPayload;
+}
+
+// Requires a valid "Authorization: Bearer <token>" header and sets request.user
+@Injectable()
+export class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const request = context.switchToHttp().getRequest<AuthenticatedRequest>();
+    const authHeader = request.headers.authorization;
+
+    if (!authHeader?.startsWith("Bearer ")) {
+      throw new UnauthorizedException(
+        "Authorization header missing or invalid"
+      );
+    }
+
+    try {
+      request.user = verifyToken(authHeader.substring("Bearer ".length));
+    } catch {
+      throw new UnauthorizedException("Invalid or expired token");
+    }
+
+    return true;
+  }
+}

package/templates/modules/auth/nestjs/src/auth/auth.module.ts.hbs

@@ -0,0 +1,22 @@
+import { Module } from "@nestjs/common";
+{{#if (eq database 'mongoose')}}
+import { MongooseModule } from "@nestjs/mongoose";
+{{/if}}
+
+{{#if (eq database 'mongoose')}}
+import { User, UserSchema } from "../users/user.schema.js";
+{{/if}}
+import { AuthController } from "./auth.controller.js";
+import { AuthService } from "./auth.service.js";
+import { UsersService } from "./users.service.js";
+
+@Module({
+  {{#if (eq database 'mongoose')}}
+  imports: [
+    MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]),
+  ],
+  {{/if}}
+  controllers: [AuthController],
+  providers: [AuthService, UsersService],
+})
+export class AuthModule {}

package/templates/modules/auth/nestjs/src/auth/auth.schemas.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+
+const MIN_PASSWORD_LENGTH = 8;
+// bcrypt ignores bytes beyond 72, so longer passwords would be silently truncated
+const MAX_PASSWORD_BYTES = 72;
+
+// Emails are trimmed and lowercased so sign-in is case-insensitive
+const emailSchema = z
+  .string("Email and password are required")
+  .trim()
+  .toLowerCase()
+  .pipe(z.email("Email must be a valid email address"));
+
+export const registerSchema = z.object({
+  email: emailSchema,
+  password: z
+    .string("Email and password are required")
+    .min(
+      MIN_PASSWORD_LENGTH,
+      `Password must be at least ${MIN_PASSWORD_LENGTH} characters`
+    )
+    .refine(
+      (password) => Buffer.byteLength(password, "utf8") <= MAX_PASSWORD_BYTES,
+      `Password must be at most ${MAX_PASSWORD_BYTES} bytes`
+    ),
+  name: z.string("Name must be a string").nullish(),
+});
+
+export const loginSchema = z.object({
+  email: emailSchema,
+  password: z.string("Email and password are required").min(1),
+});
+
+export type RegisterInput = z.infer<typeof registerSchema>;
+export type LoginInput = z.infer<typeof loginSchema>;

package/templates/modules/auth/nestjs/src/auth/auth.service.ts

@@ -0,0 +1,70 @@
+import {
+  ConflictException,
+  Injectable,
+  UnauthorizedException,
+} from "@nestjs/common";
+import bcrypt from "bcrypt";
+
+import type { LoginInput, RegisterInput } from "./auth.schemas.js";
+import { signToken } from "./jwt.js";
+import {
+  type AuthUser,
+  isDuplicateEmailError,
+  UsersService,
+} from "./users.service.js";
+
+const SALT_ROUNDS = 10;
+
+export interface AuthResponse {
+  user: Omit<AuthUser, "password">;
+  token: string;
+}
+
+@Injectable()
+export class AuthService {
+  constructor(private readonly usersService: UsersService) {}
+
+  async register({
+    email,
+    password,
+    name = null,
+  }: RegisterInput): Promise<AuthResponse> {
+    if (await this.usersService.findByEmail(email)) {
+      throw new ConflictException("User already exists");
+    }
+
+    const hashedPassword = await bcrypt.hash(password, SALT_ROUNDS);
+
+    try {
+      const user = await this.usersService.create({
+        email,
+        name,
+        password: hashedPassword,
+      });
+      return this.toAuthResponse(user);
+    } catch (error) {
+      // A concurrent request registered the same email after the check above
+      if (isDuplicateEmailError(error)) {
+        throw new ConflictException("User already exists");
+      }
+      throw error;
+    }
+  }
+
+  async login({ email, password }: LoginInput): Promise<AuthResponse> {
+    const user = await this.usersService.findByEmail(email);
+
+    if (!user || !(await bcrypt.compare(password, user.password))) {
+      throw new UnauthorizedException("Invalid credentials");
+    }
+
+    return this.toAuthResponse(user);
+  }
+
+  private toAuthResponse({ id, email, name }: AuthUser): AuthResponse {
+    return {
+      user: { id, email, name },
+      token: signToken({ sub: id, email, name }),
+    };
+  }
+}

package/templates/modules/auth/nestjs/src/auth/jwt.ts

@@ -0,0 +1,27 @@
+import jwt, { type SignOptions } from "jsonwebtoken";
+
+export interface AuthTokenPayload {
+  sub: string;
+  email: string;
+  name?: string | null;
+}
+
+const { JWT_SECRET, JWT_EXPIRES_IN } = process.env;
+
+function ensureSecret(): string {
+  if (!JWT_SECRET) {
+    throw new Error("JWT_SECRET is not set");
+  }
+  return JWT_SECRET;
+}
+
+export function signToken(payload: AuthTokenPayload): string {
+  const secret = ensureSecret();
+  const expiresIn = JWT_EXPIRES_IN || "1h";
+  return jwt.sign(payload, secret, { expiresIn } as SignOptions);
+}
+
+export function verifyToken(token: string): AuthTokenPayload {
+  const secret = ensureSecret();
+  return jwt.verify(token, secret) as AuthTokenPayload;
+}