dan86de/opti/local-explorer

Cloudflare Local Explorer Products

Use this skill when adding a new product or resource type to the local API and/or local explorer.

Start Here

Read these files before editing:

• packages/miniflare/src/workers/local-explorer/explorer.worker.ts
• packages/miniflare/src/plugins/core/explorer.ts
• packages/miniflare/src/plugins/core/types.ts
• One existing resource implementation in packages/miniflare/src/workers/local-explorer/resources/, preferably the product most similar to the new one
• One matching test in packages/miniflare/test/plugins/local-explorer/

If there are UI changes, also read:

• packages/local-explorer-ui/src/components/Sidebar.tsx
• Existing route files under packages/local-explorer-ui/src/routes/
• Existing product e2e tests under packages/local-explorer-ui/src/__e2e__/

Workflow

1. Add the API surface to packages/miniflare/scripts/openapi-filter-config.ts.
2. Generate Miniflare's filtered spec and backend types from a full Cloudflare OpenAPI spec:

OPENAPI_INPUT_PATH=<path-to-full-openapi-spec> pnpm --dir packages/miniflare generate:api

1. Inspect packages/miniflare/src/workers/local-explorer/openapi.local.json and generated types. If the generated schemas include fields local explorer will not support, add ignores in openapi-filter-config.ts and regenerate.
2. The explorer worker should have access to all user resource bindings. Ensure proxyBindings include bindings to the new product and that getExplorerServices() exposes any extra bindings the explorer worker needs. Wire product bindings through constructExplorerBindingMap() and constructExplorerWorkerOpts() in packages/miniflare/src/plugins/core/explorer.ts.
3. Add or extend resource binding metadata in packages/miniflare/src/plugins/core/types.ts.
4. Implement handlers in packages/miniflare/src/workers/local-explorer/resources/<product>.ts. Make sure to account for cross-instance aggregation, if applicable.
5. Register Hono routes in packages/miniflare/src/workers/local-explorer/explorer.worker.ts.
6. Validate request bodies and query params with generated Zod schemas from generated/zod.gen.ts using validateRequestBody() and validateQuery().
7. Return Cloudflare API envelope responses using wrapResponse() and errorResponse() from common.ts unless an existing endpoint for that product uses a different response shape.
8. Add Miniflare tests in packages/miniflare/test/plugins/local-explorer/<product>.spec.ts.
9. Regenerate the UI API client:

pnpm --dir packages/local-explorer-ui build

1. Add UI routes/components. Use Kumo components for new UI. See https://github.com/cloudflare/kumo/blob/main/AGENTS.md.
2. Add Playwright e2e tests under packages/local-explorer-ui/src/__e2e__/<product>/ for new visible product flows.

OpenAPI Rules

• Do not edit generated files like packages/miniflare/src/workers/local-explorer/openapi.local.json or packages/miniflare/src/workers/local-explorer/generated/ directly.
• Prefer upstream Cloudflare API paths when a public API exists.
• Use extensions.paths in openapi-filter-config.ts only for local-only APIs or APIs that do not exist in the public Cloudflare API.
• Add ignores for unsupported params, headers, request body properties, and response fields rather than pretending to support them.

Backend Patterns

• Local list endpoints such as listing KV namespaces should not implement pagination as this may require cross-instance aggregation. Pagination should be supported when targeting individual resources, such as listing KV keys within a specific namespace.
• For cross-worker aggregation, use aggregateListResults(), getPeerUrlsIfAggregating(), and fetchFromPeer() from aggregation.ts; do not hand-roll peer discovery. Add tests for both local-only behavior and aggregated behavior when the product can span multiple instances.
• If an API needs direct filesystem access, call through the loopback service (c.env.MINIFLARE_LOOPBACK) to a Node.js endpoint. The local explorer API runs inside workerd, so it cannot access the host filesystem directly.
• If an endpoint needs metadata that is not available on the runtime binding itself, put that metadata in BindingIdMap and pass it through CoreBindings.JSON_LOCAL_EXPLORER_BINDING_MAP.
• If a product should appear in /api/local/workers, add it to WorkerResourceBindings and populate it in constructExplorerWorkerOpts().

UI Patterns

• The UI API client is generated from packages/miniflare/src/workers/local-explorer/openapi.local.json into packages/local-explorer-ui/src/api/generated/.
• Sidebar resources come from /api/local/workers; update LocalExplorerWorkerBindings usage and Sidebar.tsx when the product should appear in navigation.
• Add route files under packages/local-explorer-ui/src/routes/. TanStack Router regenerates src/routeTree.gen.ts during UI build/dev.
• Preserve worker selection by carrying the worker search param through product links when following sidebar patterns.
• Use Kumo for new UI components wherever possible. Do not introduce a parallel component system.
• Do not use tailwindCSS color tokens, use Kumo color tokens instead.