Add Zod request and response validation

Author: wbizmo

dist/templates/api/README.md

@@ -107,6 +107,35 @@ LaunchStack CLI
 
 https://www.npmjs.com/package/launchstack-cli
 
+## Request Validation
+
+The starter uses Zod for request and response schemas.
+
+Included validation:
+
+- Registration payloads
+- Login payloads
+- Refresh-token payloads
+- Health responses
+- Authentication responses
+- Error responses
+
+Fastify uses the Zod type provider for runtime validation and TypeScript inference.
+
+## Validation Behaviour
+
+Invalid request bodies are rejected automatically with HTTP 400 responses.
+
+Examples include:
+
+- Invalid email addresses
+- Passwords shorter than eight characters
+- Missing login credentials
+- Empty refresh tokens
+- Invalid response payloads during development and testing
+
+Request types are inferred directly from Zod schemas, reducing duplication between runtime validation and TypeScript types.
+
 ## API Documentation
 
 Swagger UI:

dist/templates/api/package.json

@@ -18,7 +18,8 @@
     "db:up": "docker compose up -d postgres",
     "db:down": "docker compose down",
     "db:logs": "docker compose logs -f postgres",
-    "openapi:check": "npm run typecheck && npm test && npm run build"
+    "openapi:check": "npm run typecheck && npm test && npm run build",
+    "validation:check": "npm run typecheck && npm test && npm run build"
   },
   "dependencies": {
     "@fastify/cors": "^11.1.0",
@@ -30,7 +31,9 @@
     "fastify": "^5.6.1",
     "fastify-plugin": "^5.0.1",
     "@fastify/swagger": "^9.5.1",
-    "@fastify/swagger-ui": "^5.2.3"
+    "@fastify/swagger-ui": "^5.2.3",
+    "fastify-type-provider-zod": "^5.1.0",
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@types/node": "^25.0.0",

dist/templates/api/src/app.ts

@@ -1,6 +1,11 @@
 import Fastify, {
   type FastifyInstance
 } from "fastify";
+import {
+  serializerCompiler,
+  validatorCompiler,
+  type ZodTypeProvider
+} from "fastify-type-provider-zod";
 import { registerPlugins } from "./plugins";
 import { registerRoutes } from "./routes";
 
@@ -10,7 +15,10 @@ export async function buildApp(): Promise<FastifyInstance> {
       level: process.env.LOG_LEVEL ?? "info"
     },
     requestIdHeader: "x-request-id"
-  });
+  }).withTypeProvider<ZodTypeProvider>();
+
+  app.setValidatorCompiler(validatorCompiler);
+  app.setSerializerCompiler(serializerCompiler);
 
   await registerPlugins(app);
   await registerRoutes(app);

dist/templates/api/src/modules/auth/auth.schemas.ts

@@ -1,78 +1,85 @@
+import { z } from "zod";
+import {
+  authResponseSchema,
+  tokenPairSchema,
+  userResponseSchema
+} from "../../schemas/auth";
+import { errorResponseSchema } from "../../schemas/common";
+
+export const registerBodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+  name: z.string().trim().min(1).max(100).optional()
+});
+
+export const loginBodySchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1)
+});
+
+export const refreshBodySchema = z.object({
+  refreshToken: z.string().min(1)
+});
+
 export const registerSchema = {
   tags: ["Authentication"],
   summary: "Register a user",
-  description: "Creates a user account and returns access and refresh tokens.",
-  body: {
-    type: "object",
-    additionalProperties: false,
-    required: ["email", "password"],
-    properties: {
-      email: { type: "string", format: "email", examples: ["user@example.com"] },
-      password: { type: "string", minLength: 8, examples: ["strong-password"] },
-      name: { type: "string", minLength: 1, maxLength: 100, examples: ["Example User"] }
-    }
-  },
+  description:
+    "Creates a user account and returns access and refresh tokens.",
+  body: registerBodySchema,
   response: {
-    201: { $ref: "AuthResponse#" },
-    409: { $ref: "ErrorResponse#" }
+    201: authResponseSchema,
+    409: errorResponseSchema
   }
-} as const;
+};
 
 export const loginSchema = {
   tags: ["Authentication"],
   summary: "Log in a user",
-  description: "Authenticates credentials and returns access and refresh tokens.",
-  body: {
-    type: "object",
-    additionalProperties: false,
-    required: ["email", "password"],
-    properties: {
-      email: { type: "string", format: "email" },
-      password: { type: "string", minLength: 1 }
-    }
-  },
+  description:
+    "Authenticates credentials and returns access and refresh tokens.",
+  body: loginBodySchema,
   response: {
-    200: { $ref: "AuthResponse#" },
-    401: { $ref: "ErrorResponse#" }
+    200: authResponseSchema,
+    401: errorResponseSchema
   }
-} as const;
+};
 
 export const refreshSchema = {
   tags: ["Authentication"],
   summary: "Refresh authentication tokens",
-  description: "Rotates a valid refresh token and returns a new token pair.",
-  body: {
-    type: "object",
-    additionalProperties: false,
-    required: ["refreshToken"],
-    properties: { refreshToken: { type: "string", minLength: 1 } }
-  },
+  description:
+    "Rotates a valid refresh token and returns a new token pair.",
+  body: refreshBodySchema,
   response: {
-    200: { $ref: "TokenPair#" },
-    401: { $ref: "ErrorResponse#" }
+    200: tokenPairSchema,
+    401: errorResponseSchema
   }
-} as const;
+};
 
 export const logoutSchema = {
   tags: ["Authentication"],
   summary: "Log out a user",
-  description: "Revokes the supplied refresh token.",
-  body: {
-    type: "object",
-    additionalProperties: false,
-    required: ["refreshToken"],
-    properties: { refreshToken: { type: "string", minLength: 1 } }
-  },
-  response: { 204: { type: "null" } }
-} as const;
+  description:
+    "Revokes the supplied refresh token.",
+  body: refreshBodySchema,
+  response: {
+    204: z.null()
+  }
+};
 
 export const meSchema = {
   tags: ["Authentication"],
   summary: "Get the authenticated user",
-  description: "Returns the currently authenticated user's public profile.",
-  security: [{ bearerAuth: [] }],
+  description:
+    "Returns the currently authenticated user's public profile.",
+  security: [
+    {
+      bearerAuth: []
+    }
+  ],
   response: {
-    200: { $ref: "UserResponse#" },
-    401: { $ref: "ErrorResponse#" }
+    200: userResponseSchema,
+    401: errorResponseSchema
   }
-} as const;
+};

dist/templates/api/src/modules/auth/auth.types.ts

@@ -1,19 +1,22 @@
 import type { UserRole } from "@prisma/client";
+import type { z } from "zod";
+import type {
+  loginBodySchema,
+  refreshBodySchema,
+  registerBodySchema
+} from "./auth.schemas";
 
-export type RegisterInput = {
-  email: string;
-  password: string;
-  name?: string;
-};
+export type RegisterInput = z.infer<
+  typeof registerBodySchema
+>;
 
-export type LoginInput = {
-  email: string;
-  password: string;
-};
+export type LoginInput = z.infer<
+  typeof loginBodySchema
+>;
 
-export type RefreshInput = {
-  refreshToken: string;
-};
+export type RefreshInput = z.infer<
+  typeof refreshBodySchema
+>;
 
 export type AuthenticatedUser = {
   id: string;

dist/templates/api/src/plugins/index.ts

@@ -4,13 +4,13 @@ import { configPlugin } from "./config";
 import { corsPlugin } from "./cors";
 import { databasePlugin } from "./database";
 import { errorHandlerPlugin } from "./error-handler";
-import { schemasPlugin } from "./schemas";
 import { sensiblePlugin } from "./sensible";
 import { swaggerPlugin } from "./swagger";
 
-export async function registerPlugins(app: FastifyInstance): Promise<void> {
+export async function registerPlugins(
+  app: FastifyInstance
+): Promise<void> {
   await app.register(configPlugin);
-  await app.register(schemasPlugin);
   await app.register(swaggerPlugin);
   await app.register(databasePlugin);
   await app.register(sensiblePlugin);

dist/templates/api/src/plugins/schemas.ts

@@ -1,14 +1,21 @@
 import swagger from "@fastify/swagger";
 import swaggerUi from "@fastify/swagger-ui";
 import fp from "fastify-plugin";
+import {
+  jsonSchemaTransform,
+  jsonSchemaTransformObject
+} from "fastify-type-provider-zod";
 
 export const swaggerPlugin = fp(
   async (app) => {
     await app.register(swagger, {
+      transform: jsonSchemaTransform,
+      transformObject: jsonSchemaTransformObject,
       openapi: {
         info: {
           title: "{{PROJECT_DISPLAY_NAME}} API",
-          description: "API documentation generated by LaunchStack CLI.",
+          description:
+            "API documentation generated by LaunchStack CLI.",
           version: "0.1.0"
         },
         servers: [
@@ -18,8 +25,14 @@ export const swaggerPlugin = fp(
           }
         ],
         tags: [
-          { name: "System", description: "Health and operational endpoints" },
-          { name: "Authentication", description: "User authentication and token lifecycle" }
+          {
+            name: "System",
+            description: "Health and operational endpoints"
+          },
+          {
+            name: "Authentication",
+            description: "User authentication and token lifecycle"
+          }
         ],
         components: {
           securitySchemes: {
@@ -44,5 +57,8 @@ export const swaggerPlugin = fp(
       transformStaticCSP: (header) => header
     });
   },
-  { name: "swagger", dependencies: ["config"] }
+  {
+    name: "swagger",
+    dependencies: ["config"]
+  }
 );