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: ```bash OPENAPI_INPUT_PATH=<path-to-full-openapi-spec> pnpm --dir packages/miniflare generate:api ``` 3. 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. 4. 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`. 5. Add or extend resource binding metadata in `packages/miniflare/src/plugins/core/types.ts`. 6. Implement handlers in `packages/miniflare/src/workers/local-explorer/resources/<product>.ts`. Make sure to account for cross-instance aggregation, if applicable. 7. Register Hono routes in `packages/miniflare/src/workers/local-explorer/explorer.worker.ts`. 8. Validate request bodies and query params with generated Zod schemas from `generated/zod.gen.ts` using `validateRequestBody()` and `validateQuery()`. 9. Return Cloudflare API envelope responses using `wrapResponse()` and `errorResponse()` from `common.ts` unless an existing endpoint for that product uses a different response shape. 10. Add Miniflare tests in `packages/miniflare/test/plugins/local-explorer/<product>.spec.ts`. 11. Regenerate the UI API client: ```bash pnpm --dir packages/local-explorer-ui build ``` 12. Add UI routes/components. Use Kumo components for new UI. See https://github.com/cloudflare/kumo/blob/main/AGENTS.md. 13. 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. --- > Source: [cloudflare/workers-sdk](https://github.com/cloudflare/workers-sdk) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill_md:2026-06-30 -->