⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
write-endpoints
Comprehensive guide for building OpenAPI endpoints with chanfana - schema definition, request validation, CRUD operations, D1 database integration, and exception handling
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Documentation: chanfana.pages.dev
Source Code: github.com/cloudflare/chanfana
Overview
chanfana (previously known as itty-router-openapi) is a library that adds OpenAPI schema generation and validation to any router ( Hono, itty-router, etc), meant to be a powerful and lightweight library for Cloudflare Workers but runs on any runtime supported by the base router.
The key features are:
- OpenAPI 3 and 3.1 schema generator and validator
- Zod v4 compatible with full TypeScript inference
- Fully written in typescript
- Class-based endpoints
- Query, Path, Headers, and Body typescript inference, see Parameters and Request Validation
- Extend existing Hono, itty-router, etc application, without touching old routes
- CLI to extract the schema.json from your code (npx chanfana) - see CLI Documentation
AI Skills
Chanfana provides AI coding assistant skills to help you build OpenAPI endpoints faster. Install them using npx skills:
npx skills install cloudflare/chanfana
Available skills:
- write-endpoints - Comprehensive guide for building OpenAPI endpoints with schema definition, request validation, CRUD operations, and D1 integration
Getting started
Or scaffold it locally with the create-cloudflare CLI:
npm create cloudflare@latest -- --template https://github.com/cloudflare/chanfana/tree/main/template
The template includes a complete Task API with Hono, D1, and Zod v4 — full CRUD endpoints, a custom endpoint example, integration tests, and auto-generated docs at /api/docs.
See template/README.md for full setup instructions.
Installation
npm i chanfana --save
Command-Line Interface (CLI)
Chanfana includes a CLI tool to help you extract the OpenAPI schema from your Cloudflare Worker project. This is useful for generating a static schema file, for example, in CI/CD pipelines.
The basic command is:
npx chanfana
This will start your worker using wrangler dev, fetch the schema from /openapi.json, and save it to schema.json.
For more details on options and usage, please refer to the CLI Documentation.
Minimal Hono Example
import { fromHono, OpenAPIRoute } from 'chanfana'
import { Hono } from 'hono'
import { z } from 'zod'
export type Env = {
// Example bindings
DB: D1Database
BUCKET: R2Bucket
}
export type AppContext = Context<{ Bindings: Env }>
export class GetPageNumber extends OpenAPIRoute {
schema = {
request: {
params: z.object({
id: z.string().min(2).max(10),
}),
query: z.object({
page: z.number().int().min(0).max(20),
}),
},
}
async handle(c: AppContext) {
const data = await this.getValidatedData<typeof this.schema>()
return c.json({
id: data.params.id,
page: data.query.page,
})
}
}
// Start a Hono app
const app = new Hono<{ Bindings: Env }>()
// Setup OpenAPI registry
const openapi = fromHono(app)
// Register OpenAPI endpoints (this will also register the routes in Hono)
openapi.get('/entry/:id', GetPageNumber)
// Export the Hono app
export default app
Feedback and contributions
chanfana aims to be at the core of new APIs built using Workers and define a pattern to allow everyone to have an OpenAPI-compliant schema without worrying about implementation details or reinventing the wheel.
chanfana is considered stable and production ready and is being used with the Radar 2.0 public API and many other Cloudflare products.
See CONTRIBUTING.md for how to set up the project and submit changes.
You can also talk to us in the Cloudflare Community or the Radar Discord Channel
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/write-endpoints/SKILL.md26 KB83968d668b79upstream ↗
--- name: write-endpoints description: Comprehensive guide for building OpenAPI endpoints with chanfana - schema definition, request validation, CRUD operations, D1 database integration, and exception handling --- # Writing OpenAPI Endpoints with Chanfana ## When to Use Use this skill when: - Building OpenAPI endpoints with chanfana for Cloudflare Workers - Defining request/response schemas with Zod v4 - Creating CRUD auto endpoints (Create, Read, Update, Delete, List) - Integrating with Cloudflare D1 databases - Implementing error handling with exception classes ## Part 1: Fundamentals ### Quick Start with Hono ```typescript import { Hono, type Context } from 'hono'; import { fromHono, OpenAPIRoute, contentJson } from 'chanfana'; import { z } from 'zod'; export type Env = { DB: D1Database; }; export type AppContext = Context<{ Bindings: Env }>; class HelloEndpoint extends OpenAPIRoute { schema = { responses: { "200": { description: 'Successful response', ...contentJson(z.object({ message: z.string() })), }, }, }; async handle(c: AppContext) { return { message: 'Hello, Chanfana!' }; } } const app = new Hono<{ Bindings: Env }>(); const openapi = fromHono(app); openapi.get('/hello', HelloEndpoint); export default app; ``` ### Quick Start with itty-router ```typescript import { Router } from 'itty-router'; import { fromIttyRouter, OpenAPIRoute, contentJson } from 'chanfana'; import { z } from 'zod'; class HelloEndpoint extends OpenAPIRoute { schema = { responses: { "200": { description: 'Successful response', ...contentJson(z.object({ message: z.string() })), }, }, }; async handle(request: Request, env, ctx) { return { message: 'Hello, Chanfana!' }; } } const router = Router(); const openapi = fromIttyRouter(router); openapi.get('/hello', HelloEndpoint); router.all('*', () => new Response("Not Found.", { status: 404 })); export const fetch = router.handle; ``` ### Schema Definition Define request validation for body, query, params, and headers: ```typescript import { OpenAPIRoute, contentJson } from 'chanfana'; import { z } from 'zod'; class CreateUserEndpoint extends OpenAPIRoute { schema = { request: { body: contentJson(z.object({ username: z.string().min(3).max(20), password: z.string().min(8), email: z.email(), fullName: z.string().optional(), })), query: z.object({ notify: z.boolean().optional().default(true), }), params: z.object({ orgId: z.uuid(), }), headers: z.object({ 'X-API-Key': z.string(), }), }, responses: { "200": { description: 'User created successfully', ...contentJson(z.object({ id: z.uuid(), username: z.string(), email: z.email(), })), }, "400": { description: 'Validation error', ...contentJson(z.object({ success: z.literal(false), errors: z.array(z.object({ code: z.number(), message: z.string(), })), })), }, }, }; async handle(c) { const data = await this.getValidatedData<typeof this.schema>(); // data.body, data.query, data.params, data.headers are all typed return { id: crypto.randomUUID(), username: data.body.username, email: data.body.email }; } } ``` ### Zod v4 Syntax (CRITICAL) Chanfana v3 uses Zod v4. Use the correct syntax: ```typescript // WRONG - Zod v3 syntax (deprecated) z.string().email() z.string().uuid() z.string().datetime() z.string().date() z.string().url() z.string().ip({ version: "v4" }) z.object({}).strict() z.nativeEnum(MyEnum) // CORRECT - Zod v4 syntax z.email() z.uuid() z.iso.datetime() z.iso.date() z.url() z.ipv4() z.strictObject({}) z.enum(['option1', 'option2']) ``` ### Common Zod Types for APIs Use native Zod schemas for all parameter types: ```typescript import { z } from 'zod'; // String with constraints const nameSchema = z.string() .min(3) .max(50) .describe("User's name") .openapi({ example: 'John Doe' }); // Number with range const priceSchema = z.number() .min(0) .describe('Product price') .openapi({ example: 99.99 }); // Integer const ageSchema = z.number() .int() .min(0) .max(120) .describe("User's age"); // Boolean with default const isActiveSchema = z.boolean() .default(true) .describe('User active status'); // Date/time (ISO 8601) const createdAtSchema = z.iso.datetime() .describe('Creation timestamp') .openapi({ example: '2024-01-20T10:30:00Z' }); // Date only (YYYY-MM-DD) const birthDateSchema = z.iso.date() .describe('Birth date') .openapi({ example: '1990-05-15' }); // Email, UUID const emailSchema = z.email().describe('Email address'); const userIdSchema = z.uuid().describe('User ID'); // Enumeration const statusSchema = z.enum(['pending', 'processing', 'shipped', 'delivered']) .default('pending') .describe('Order status'); // Array const tagsSchema = z.array(z.string()).openapi({ description: 'Tags', }); // Object const addressSchema = z.object({ street: z.string().describe('Street address'), city: z.string().describe('City'), zipCode: z.string().describe('Zip code'), }); // Regex pattern const phoneSchema = z.string() .regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number format') .describe('Phone number'); // IP addresses const ipv4Schema = z.ipv4(); const ipv6Schema = z.ipv6(); const ipSchema = z.union([z.ipv4(), z.ipv6()]); // Hostname (regex pattern) const hostnameSchema = z.string().regex( /^(([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])\.)*([A-Za-z0-9]|[A-Za-z0-9][A-Za-z0-9-]*[A-Za-z0-9])$/ ); ``` ### Validated Data Access Always use `await` with `getValidatedData()`: ```typescript class MyEndpoint extends OpenAPIRoute { async handle(c) { // CORRECT - with await and type annotation const data = await this.getValidatedData<typeof this.schema>(); // Type-safe access const username = data.body.username; const page = data.query.page; const userId = data.params.userId; const apiKey = data.headers['X-API-Key']; return { success: true }; } } ``` ### Using getUnvalidatedData() for Partial Updates In Zod v4, optional fields with `.default()` always have values in validated data. Use `getUnvalidatedData()` to detect what was actually sent: ```typescript class UpdateUser extends OpenAPIRoute { schema = { request: { body: contentJson(z.object({ name: z.string().optional(), status: z.enum(['active', 'inactive']).default('active'), })), }, }; async handle() { const validated = await this.getValidatedData<typeof this.schema>(); // validated.body.status is 'active' even if not sent const raw = await this.getUnvalidatedData(); // raw.body = {} if nothing was sent // Check what was actually sent const updates: Record<string, any> = {}; if ('name' in raw.body) updates.name = validated.body.name; if ('status' in raw.body) updates.status = validated.body.status; return { updated: updates }; } } ``` ### Route Middleware and Validated Data in Middleware (Hono only) Hono middleware can be placed before the endpoint class. To read the endpoint's validated data in middleware, add the opt-in `chanfanaValidator()` marker: middleware after it get typed `c.req.valid('json' | 'query' | 'param' | 'header')` (Zod output, coerced and defaulted), and the endpoint reuses that data instead of validating twice. ```typescript import { chanfanaValidator } from 'chanfana'; openapi.post('/users', authMiddleware, CreateUser); // plain middleware, typed like Hono openapi.post( '/users', authMiddleware, // before the marker: no c.req.valid() chanfanaValidator(), // validates against CreateUser's schema, same 400/7001 on failure async (c, next) => { const { email } = c.req.valid('json'); // typed from CreateUser.schema return next(); }, CreateUser, // must come last, after the marker ); ``` Rules: - `fromHono()` only. Using it with `fromIttyRouter()`, in `app.use()`, twice in a route, or in a route that doesn't end with a single endpoint class throws at registration. - No `'json'` on `get()` routes; on `all()` routes it is typed `T | undefined` (GET/HEAD requests have no body). - Typed for up to 5 middleware before the endpoint; longer chains are untyped. - `c.req.valid()` is only typed when `schema` has a literal type (not annotated `OpenAPIRouteSchema`, not built in `getSchema()`); otherwise it is `any`. - The endpoint's `handle()` context is not typed from the chain. Middleware that mutate `c.req.valid()` objects change what the endpoint sees. ## Part 2: CRUD Auto Endpoints ### Meta Object Definition All auto endpoints require a `_meta` property: ```typescript import { z } from 'zod'; // Define the model schema const UserSchema = z.object({ id: z.uuid(), username: z.string().min(3).max(20), email: z.email(), role: z.enum(['user', 'admin']), createdAt: z.iso.datetime(), }); // Define the meta object const userMeta = { model: { schema: UserSchema, // Required: Zod schema for the model primaryKeys: ['id'], // Required: Array of primary key fields tableName: 'users', // Required for D1 endpoints serializer: (user: any) => { // Optional: Transform output const { passwordHash, ...safe } = user; return safe; }, serializerSchema: UserSchema.omit({ passwordHash: true }), // Optional: Schema for serialized output }, pathParameters: ['id'], // Optional: Explicit path params for nested routes tags: ['Users'], // Optional: OpenAPI tags for grouping operations }; ``` ### CreateEndpoint ```typescript import { CreateEndpoint, type O } from 'chanfana'; class CreateUser extends CreateEndpoint { _meta = userMeta; // Optional: Pre-processing hook async before(data: O<typeof this._meta>): Promise<O<typeof this._meta>> { return { ...data, id: crypto.randomUUID(), createdAt: new Date().toISOString(), }; } // Required: Create logic async create(data: O<typeof this._meta>) { await db.users.insert(data); return data; } // Optional: Post-processing hook async after(data: O<typeof this._meta>): Promise<O<typeof this._meta>> { await sendWelcomeEmail(data.email); return data; } } // Register route openapi.post('/users', CreateUser); ``` ### ReadEndpoint ```typescript import { ReadEndpoint, type Filters, type O } from 'chanfana'; class GetUser extends ReadEndpoint { _meta = userMeta; async before(filters: Filters): Promise<Filters> { // Pre-fetch validation return filters; } async fetch(filters: Filters): Promise<O<typeof this._meta> | null> { const userId = filters.filters[0].value; return await db.users.findById(userId); } async after(data: O<typeof this._meta>): Promise<O<typeof this._meta>> { // Post-fetch processing return data; } } // Register route with path parameter openapi.get('/users/:id', GetUser); ``` ### ListEndpoint ```typescript import { ListEndpoint, type ListFilters, type ListResult, type O } from 'chanfana'; class ListUsers extends ListEndpoint { _meta = userMeta; // Configure filtering, search, and sorting filterFields = ['role', 'status']; // Exact match filtering searchFields = ['username', 'email']; // Full-text search (LIKE) orderByFields = ['createdAt', 'username']; // Available sort fields defaultOrderBy = 'createdAt'; // Default sort field async before(filters: ListFilters): Promise<ListFilters> { // Add tenant filter, etc. return filters; } async list(filters: ListFilters): Promise<ListResult<O<typeof this._meta>>> { const users = await db.users.findMany(filters); return { result: users }; } async after(data: ListResult<O<typeof this._meta>>): Promise<ListResult<O<typeof this._meta>>> { return data; } } // Register route openapi.get('/users', ListUsers); // API calls: // GET /users?page=2&per_page=10 // GET /users?role=admin // GET /users?search=john // GET /users?order_by=createdAt&order_by_direction=desc ``` ### UpdateEndpoint ```typescript import { UpdateEndpoint, type UpdateFilters, type O } from 'chanfana'; class UpdateUser extends UpdateEndpoint { _meta = userMeta; async before(oldObj: O<typeof this._meta>, filters: UpdateFilters): Promise<UpdateFilters> { filters.updatedData = { ...filters.updatedData, updatedAt: new Date().toISOString(), }; return filters; } async getObject(filters: UpdateFilters): Promise<O<typeof this._meta> | null> { const userId = filters.filters[0].value; return await db.users.findById(userId); } async update(oldObj: O<typeof this._meta>, filters: UpdateFilters): Promise<O<typeof this._meta>> { const userId = filters.filters[0].value; return await db.users.update(userId, { ...oldObj, ...filters.updatedData }); } async after(data: O<typeof this._meta>): Promise<O<typeof this._meta>> { await cache.invalidate(`user:${data.id}`); return data; } } // Register route openapi.put('/users/:id', UpdateUser); ``` ### DeleteEndpoint ```typescript import { DeleteEndpoint, type Filters, type O } from 'chanfana'; class DeleteUser extends DeleteEndpoint { _meta = userMeta; async before(oldObj: O<typeof this._meta>, filters: Filters): Promise<Filters> { await checkDeletionPermissions(oldObj.id); return filters; } async getObject(filters: Filters): Promise<O<typeof this._meta> | null> { const userId = filters.filters[0].value; return await db.users.findById(userId); } async delete(oldObj: O<typeof this._meta>, filters: Filters): Promise<O<typeof this._meta> | null> { const userId = filters.filters[0].value; await db.users.delete(userId); return oldObj; } async after(data: O<typeof this._meta>): Promise<O<typeof this._meta>> { await auditLog.record('user_deleted', data.id); return data; } } // Register route openapi.delete('/users/:id', DeleteUser); ``` ### Nested Routes with pathParameters For composite primary keys in nested routes: ```typescript const PostSchema = z.object({ userId: z.uuid(), id: z.uuid(), title: z.string(), content: z.string(), }); const postMeta = { model: { schema: PostSchema, primaryKeys: ['userId', 'id'], // Composite primary key tableName: 'posts', }, pathParameters: ['userId', 'id'], // Explicit path params }; class GetPost extends ReadEndpoint { _meta = postMeta; async fetch(filters: Filters) { const userId = filters.filters.find(f => f.field === 'userId')?.value; const postId = filters.filters.find(f => f.field === 'id')?.value; return await db.posts.findOne({ userId, id: postId }); } } // Nested route: /users/:userId/posts/:id const postsRouter = new Hono(); const postsOpenapi = fromHono(postsRouter); postsOpenapi.get('/:id', GetPost); // Mount nested router openapi.route('/:userId/posts', postsOpenapi); ``` ## Part 3: D1 Database Integration ### D1 Endpoint Classes D1 endpoints extend CRUD endpoints with built-in database operations: ```typescript import { D1CreateEndpoint, D1ReadEndpoint, D1UpdateEndpoint, D1DeleteEndpoint, D1ListEndpoint, InputValidationException, } from 'chanfana'; // wrangler.toml: // [[d1_databases]] // binding = "DB" // database_name = "my-database" // database_id = "your-database-id" class CreateUser extends D1CreateEndpoint { _meta = userMeta; dbName = 'DB'; // Must match wrangler.toml binding name // Optional: Handle UNIQUE constraint violations constraintsMessages = { 'users_email_unique': new InputValidationException( 'Email already registered', ['body', 'email'] ), 'users_username_unique': new InputValidationException( 'Username already taken', ['body', 'username'] ), }; // Optional: Enable logging logger = console; } class GetUser extends D1ReadEndpoint { _meta = userMeta; dbName = 'DB'; } class UpdateUser extends D1UpdateEndpoint { _meta = userMeta; dbName = 'DB'; } class DeleteUser extends D1DeleteEndpoint { _meta = userMeta; dbName = 'DB'; } class ListUsers extends D1ListEndpoint { _meta = userMeta; dbName = 'DB'; filterFields = ['role', 'status']; searchFields = ['username', 'email']; orderByFields = ['createdAt', 'username']; defaultOrderBy = 'createdAt'; } // Register routes const app = new Hono<{ Bindings: { DB: D1Database } }>(); const openapi = fromHono(app); openapi.post('/users', CreateUser); openapi.get('/users', ListUsers); openapi.get('/users/:id', GetUser); openapi.put('/users/:id', UpdateUser); openapi.delete('/users/:id', DeleteUser); ``` ### SQL Injection Prevention D1 endpoints include built-in security utilities: ```typescript import { validateSqlIdentifier, validateTableName, validateColumnName, buildSafeFilters, } from 'chanfana/endpoints/d1/base'; // Validate identifiers const table = validateTableName('users'); // OK const column = validateColumnName('email'); // OK validateTableName('DROP TABLE--'); // Throws ApiException // Build safe WHERE clauses const filters = [ { field: 'status', operator: 'EQ', value: 'active' }, { field: 'role', operator: 'EQ', value: 'admin' }, ]; const validColumns = ['id', 'status', 'role', 'name']; const { conditions, conditionsParams } = buildSafeFilters(filters, validColumns); // conditions: ['status = ?1', 'role = ?2'] // conditionsParams: ['active', 'admin'] ``` ## Part 4: Error Handling ### Exception Classes | Exception | Status | Code | Default Message | Special Properties | |-----------|--------|------|-----------------|-------------------| | `ApiException` | 500 | 7000 | "Internal Error" | Base class | | `InputValidationException` | 400 | 7001 | "Input Validation Error" | `path` | | `NotFoundException` | 404 | 7002 | "Not Found" | - | | `UnauthorizedException` | 401 | 7003 | "Unauthorized" | - | | `ForbiddenException` | 403 | 7004 | "Forbidden" | - | | `MethodNotAllowedException` | 405 | 7005 | "Method Not Allowed" | - | | `ConflictException` | 409 | 7006 | "Conflict" | - | | `UnprocessableEntityException` | 422 | 7007 | "Unprocessable Entity" | `path` | | `TooManyRequestsException` | 429 | 7008 | "Too Many Requests" | `retryAfter` | | `InternalServerErrorException` | 500 | 7009 | "Internal Server Error" | `isVisible: false` | | `BadGatewayException` | 502 | 7010 | "Bad Gateway" | - | | `ServiceUnavailableException` | 503 | 7011 | "Service Unavailable" | `retryAfter` | | `GatewayTimeoutException` | 504 | 7012 | "Gateway Timeout" | - | ### Throwing Exceptions ```typescript import { InputValidationException, NotFoundException, UnauthorizedException, ForbiddenException, ConflictException, TooManyRequestsException, MultiException, } from 'chanfana'; class MyEndpoint extends OpenAPIRoute { async handle(c) { // Validation error with path if (!isValidEmail(email)) { throw new InputValidationException('Invalid email format', ['body', 'email']); } // Not found const user = await db.users.findById(id); if (!user) { throw new NotFoundException(`User ${id} not found`); } // Authentication required if (!c.req.header('Authorization')) { throw new UnauthorizedException('Authentication required'); } // Permission denied if (!user.hasPermission('admin')) { throw new ForbiddenException('Admin access required'); } // Resource conflict if (await db.users.existsByEmail(email)) { throw new ConflictException('Email already registered'); } // Rate limiting if (rateLimitExceeded) { throw new TooManyRequestsException('Rate limit exceeded', 60); // retry after 60s } // Multiple errors const errors = []; if (field1Invalid) errors.push(new InputValidationException('Field 1 invalid', ['body', 'field1'])); if (field2Invalid) errors.push(new InputValidationException('Field 2 invalid', ['body', 'field2'])); if (errors.length > 0) { throw new MultiException(errors); } return { success: true }; } } ``` ### Documenting Exceptions in Schema ```typescript import { OpenAPIRoute, contentJson, InputValidationException, NotFoundException, UnauthorizedException, } from 'chanfana'; class GetUser extends OpenAPIRoute { schema = { request: { params: z.object({ id: z.uuid() }), }, responses: { "200": { description: 'User found', ...contentJson(UserSchema), }, ...InputValidationException.schema(), // Documents 400 response ...UnauthorizedException.schema(), // Documents 401 response ...NotFoundException.schema(), // Documents 404 response }, }; } ``` ## Part 5: Verification ### Checklist **Basic Endpoints:** - [ ] Schema defines `responses` (required, even if just 200) - [ ] Using `contentJson()` wrapper for JSON request/response bodies - [ ] Using `await this.getValidatedData<typeof this.schema>()` for type-safe access - [ ] Using Zod v4 syntax (`z.email()` not `z.string().email()`) - [ ] Path parameters in schema match route definition (`:userId` -> `params: z.object({ userId: ... })`) - [ ] Exception responses documented using `...ExceptionClass.schema()` spread **CRUD Auto Endpoints:** - [ ] `_meta` property is defined on the endpoint class - [ ] `_meta.model.schema` is a valid Zod object schema - [ ] `_meta.model.primaryKeys` is an array of primary key field names - [ ] `_meta.model.tableName` is set (required for D1 endpoints) - [ ] Nested routes use `pathParameters` in meta for composite primary keys - [ ] `_meta.tags` is set to group related endpoints under OpenAPI tags - [ ] ListEndpoint has `filterFields`, `searchFields`, `orderByFields` configured as needed **D1 Endpoints:** - [ ] `dbName` matches the binding name in wrangler.toml - [ ] `constraintsMessages` defined for UNIQUE constraint handling - [ ] Hono app typed with `{ Bindings: { DB: D1Database } }` ### Common Mistakes **1. Missing contentJson wrapper** ```typescript // WRONG - response body not properly documented responses: { "200": { description: 'Success', content: { 'application/json': { schema: z.object({...}) } } } } // CORRECT - use contentJson helper responses: { "200": { description: 'Success', ...contentJson(z.object({...})) } } ``` **2. Not awaiting getValidatedData** ```typescript // WRONG - missing await const data = this.getValidatedData<typeof this.schema>(); // CORRECT const data = await this.getValidatedData<typeof this.schema>(); ``` **3. Using Zod v3 syntax** ```typescript // WRONG - Zod v3 syntax z.string().email() z.string().datetime() z.object({}).strict() // CORRECT - Zod v4 syntax z.email() z.iso.datetime() z.strictObject({}) ``` **4. Forgetting response schema** ```typescript // WRONG - no responses defined schema = { request: { ... } } // CORRECT - always define responses schema = { request: { ... }, responses: { "200": { description: 'Success', ...contentJson(...) } } } ``` **5. Primary key mismatch in nested routes** ```typescript // WRONG - composite key not reflected in pathParameters const postMeta = { model: { primaryKeys: ['userId', 'postId'], } }; // Route: /users/:userId/posts/:postId but no pathParameters // CORRECT - explicitly define pathParameters const postMeta = { model: { primaryKeys: ['userId', 'postId'], }, pathParameters: ['userId', 'postId'], }; ``` **6. Optional fields with defaults in Zod v4** ```typescript // GOTCHA - Zod v4 always provides default values const data = await this.getValidatedData(); // data.body.status is 'active' even if not sent in request // SOLUTION - use getUnvalidatedData() to check what was actually sent const raw = await this.getUnvalidatedData(); if ('status' in raw.body) { // status was actually sent } ``` **7. D1 binding name mismatch** ```typescript // WRONG - binding name doesn't match wrangler.toml class MyEndpoint extends D1CreateEndpoint { dbName = 'DATABASE'; // wrangler.toml has binding = "DB" } // CORRECT class MyEndpoint extends D1CreateEndpoint { dbName = 'DB'; // matches wrangler.toml [[d1_databases]] binding } ``` **8. Missing _meta in auto endpoints** ```typescript // WRONG - no _meta defined class CreateUser extends CreateEndpoint { async create(data) { ... } } // CORRECT - _meta is required class CreateUser extends CreateEndpoint { _meta = { model: { schema: UserSchema, primaryKeys: ['id'], tableName: 'users', }, }; async create(data) { ... } } ``` **9. Using nativeEnum in Zod v4** ```typescript // WRONG - Zod v3 syntax enum Status { Active = 'active', Inactive = 'inactive' } z.nativeEnum(Status) // CORRECT - Zod v4 syntax z.enum(['active', 'inactive']) ```README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/cloudflare-chanfana-skills-write-endpoints.md