worktop: Edge-Native Web Framework

Common errors

• TypeError: API.add is not a function

  cause Attempting to call `.add` on an incorrectly imported `API` object, or using an older version that might not export `API` directly in the same manner.
  fix Ensure you are importing `Router` correctly with `import { Router } from 'worktop'` and then instantiating it with `const API = new Router();`. For older versions, check the specific import paths and usage patterns.

• ReferenceError: structuredClone is not defined

  cause Running `worktop` on an older Cloudflare Workers runtime or a non-Workers environment that lacks support for the `structuredClone` global function, despite `worktop` shipping types for it in newer versions.
  fix Update your Cloudflare Workers deployment to use a recent compatibility date in `wrangler.toml` that enables `structuredClone`. If running in a different environment, ensure it provides the `structuredClone` global or polyfill it if feasible and necessary for your application logic.

• The 'wild' parameter is not defined in context.params

  cause Attempting to access a wildcard route parameter using `context.params.wild` after upgrading to `worktop@0.8.0-next.18` or later, which changed the wildcard key.
  fix Access wildcard route parameters using `context.params['*']` instead of `context.params.wild`. For example, `const value = context.params['*']`.

Warnings

• breaking The `0.8.0-next` series introduces a fundamental shift towards platform agnosticism. This includes significant internal refactoring, module renaming (e.g., `worktop/kv` to `worktop/cfw.kv`), and removal of previously available APIs (e.g., `start` from `worktop/sw` or `worktop/cache`). Applications updating from `0.7.x` will require substantial code modifications to adapt to the new modular structure and API surface.
  Fix: Review the `0.8.0-next.x` changelogs carefully. Migrate Cloudflare-specific imports to their new `worktop/cfw.*` paths. Adapt to the new `listen` entry point for handling requests. Refer to the official `worktop` documentation for the `0.8.x` branch.
• breaking The matching behavior of optional wildcard routes (e.g., `/books/*?`) has changed due to an upgrade to `regexparam@3.0`. Additionally, the key used for capturing wildcard values in `context.params` changed from `'wild'` to `'*'`.
  Fix: Update route definitions to reflect the new `regexparam` behavior. Access wildcard values using `context.params['*']` instead of `context.params.wild`.
• breaking The `worktop/cfw.kv` module's `Entity` class, used for KV data management, now strictly enforces JSON data for storage. This ensures data consistency and simplifies serialization but breaks compatibility with non-JSON `Entity` usages.
  Fix: Ensure all data stored via `worktop/cfw.kv` `Entity` instances is valid JSON. Convert non-JSON data types to JSON-serializable formats before persisting them.
• gotcha TypeScript type definitions for Web APIs such as `structuredClone`, `queueMicrotask`, and `HTMLRewriter` for Cloudflare Workers were missing or incorrect in earlier `0.8.0-next` releases, leading to potential type errors in projects using strict TypeScript configurations.
  Fix: Upgrade to `worktop@0.8.0-next.15` or later to ensure proper type definitions for these standard Web APIs in Cloudflare Workers environments. Alternatively, manually declare global types if an upgrade is not immediately possible.

Install

• npm install worktop npm
• yarn add worktop yarn
• pnpm add worktop pnpm

Imports

• Router
  wrong:

  const { Router } = require('worktop')

  correct:

  import { Router } from 'worktop'

  ESM imports are standard. CommonJS `require` syntax is not supported in recent versions and edge runtimes.
• listen
  wrong:

  import { start } from 'worktop/sw'

  correct:

  import { listen } from 'worktop'

  `listen` is for starting the server. In `0.8.0-next.10` and later, `start` from `worktop/sw` or `worktop/cache` was removed; use `listen` from the core module.
• KV
  wrong:

  import { KV } from 'worktop/kv'

  correct:

  import { KV } from 'worktop/cfw.kv'

  Since `0.8.0-next.10`, Cloudflare-specific modules like KV storage have moved to namespaced submodules (e.g., `worktop/cfw.kv`) to maintain platform agnosticism of the core.

Quickstart

This example sets up a basic `worktop` router with a dynamic GET endpoint and a catch-all route for Cloudflare Workers, demonstrating parameter extraction and static asset serving for Pages.

import { Router, listen } from 'worktop';

const API = new Router();

// A basic GET endpoint
API.add('GET', '/hello/:name', (request, context) => {
  const name = context.params.name ?? 'World';
  return new Response(`Hello, ${name}!`);
});

// A catch-all route for other paths or methods, serving static assets for Cloudflare Workers Pages
API.add('GET', '/*', (request, context) => {
  // For Cloudflare Workers Pages, `env.ASSETS.fetch` is used to serve static files.
  // This assumes 'ASSETS' is bound in your wrangler.toml file.
  // If not using Pages or static assets, this route would typically return a 404.
  const url = new URL(request.url);
  if (url.pathname.startsWith('/api')) {
    // If the request was for an API route not matched above, return a 404
    return new Response('Not Found', { status: 404 });
  }
  // Otherwise, attempt to serve a static asset if ASSETS binding exists
  // This pattern is common when combining Worker API with static site hosting.
  if (context.bindings && context.bindings.ASSETS) {
    return context.bindings.ASSETS.fetch(request);
  }
  return new Response('Not Found', { status: 404 });
});

// Listen for incoming requests on the Workers environment
listen(API.handler);