Terminal
Terminal/Skill
Guide for configuring Zuplo API gateway routes, policies, and custom handlers, using current official docs as the source.
By Zuplo
Works with
npx skills add zuplo/tools --skill zuplo-guideBuild and manage programmable API gateways with Zuplo. This skill teaches you how to find current documentation and correctly configure Zuplo projects.
Before configuring ANY Zuplo feature (policies, handlers, routes, CORS, rate limiting, auth, etc.), you MUST read the relevant documentation first. Do not rely on training data for Zuplo-specific configuration. The docs are the source of truth for correct configuration format, required fields, and available options.
If you skip this step and produce incorrect configuration, it will break the user's project.
Use the following sources in priority order:
Local docs (preferred): The zuplo npm package bundles full documentation. Look for docs at node_modules/zuplo/docs/ (check both the project root and parent directories for monorepos or hoisted installs). These are version-matched and always available offline.
MCP server tools: If the Zuplo MCP server is connected, use search-zuplo-docs and ask-question-about-zuplo (may be prefixed, e.g. mcp__*Zuplo*__search-zuplo-docs).
Fetch docs via URL: Fetch https://zuplo.com/docs/llms.txt for a page index, then fetch individual pages. Policy catalog: https://cdn.zuplo.com/portal/policies.v5.json.
| Topic | Path in node_modules/zuplo/docs/ |
|---|---|
| Concepts (request lifecycle, project structure) | concepts/ |
| Policies (index + per-policy config/schema) | policies/_index.md, policies/{policy-id}/doc.md, policies/{policy-id}/schema.json |
| Handlers (URL forward, rewrite, custom, etc.) | handlers/ |
| Articles (CORS, env vars, auth, deployment) | articles/ |
| CLI reference | cli/ |
| Monetization | articles/monetization/ |
| Developer portal / Zudoku | dev-portal/ |
| Programmable API reference | programmable-api/ |
| Guides | guides/ |
Zuplo is a programmable API gateway built on web standards. Key principles:
routes.oas.json is both the API spec and the routing configRequest, Response, Headers, fetch(), Web Crypto, Streams (no Node.js APIs)zuplo.jsonc # Project config (version, compatibilityDate)
/config/
routes.oas.json # OpenAPI 3.1 spec = routing configuration
/modules/
*.ts # Custom handlers, policies, shared utilities
zuplo.runtime.ts # Global runtime extensions and hooks
Request → Pre-Routing Hooks → Route Matching → Request Hooks
→ Inbound Policies (auth, rate limiting — can short-circuit)
→ Handler (core logic)
→ Outbound Policies (response transformation)
→ Response Hooks → Response sent
→ waitUntil tasks (background work)
import {
ZuploRequest, ZuploContext, RuntimeExtensions, HttpProblems,
ZoneCache, environment,
} from "@zuplo/runtime";
For full details on handlers, runtime objects, caching, authentication, and deployment models, read the docs in node_modules/zuplo/docs/concepts/.
node_modules/zuplo/docs/ first)node_modules/zuplo/docs/ or use MCP toolsnode_modules/zuplo/docs/policies/_index.md for the full list, then the specific policy's doc.md for configuration