API Routes

API routes live in src/api/ and can be written in TypeScript/JavaScript or Go. Both compile into the same /api/* namespace and can be mixed per route. When a .go and a .ts/.js file map to the same /api path, the compiled Go route takes precedence.

Route mapping follows the page convention:

File	Route
src/api/hello.ts	/api/hello
src/api/users/index.go	/api/users
src/api/users/[id].go	/api/users/{id}

JS/TS routes

JS/TS routes are compiled to JS and served via a Node.js sidecar (port 3001) or the embedded QuickJS runtime.

Modern pattern (recommended): named method exports

// src/api/users.ts export async function GET(request: Request) { const users = await db.getUsers(); return Response.json(users); } export async function POST(request: Request) { const body = await request.json(); const user = await db.createUser(body); return Response.json(user, { status: 201 }); }

Legacy pattern: default export

// src/api/legacy.ts export default function handler(req, res) { res.json({ message: 'legacy pattern' }); }

Go routes

Go routes (src/api/*.go) are compiled into a dedicated Go sidecar binary (.krate/goapi-server[.exe], port +2) for maximum performance and true concurrency.

// src/api/hello.go — GET /api/hello package api import ( "net/http" "krate-goapi/runtime" ) func GET(w http.ResponseWriter, r *http.Request) { runtime.WriteJSON(w, 200, map[string]interface{}{"hello": "world"}) }

Each file defines a Handler(w, r) function for all methods, and/or named GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD functions for per-method dispatch. Dynamic segments use [param] file names and are read with r.PathValue("param"):

// src/api/users/[id].go — all methods on /api/users/{id} func Handler(w http.ResponseWriter, r *http.Request) { runtime.WriteJSON(w, 200, map[string]interface{}{"id": r.PathValue("id")}) }

Go routes require the Go toolchain at build time and should stick to the stdlib plus the krate-goapi/runtime helper package.