{"id":12677,"library":"worktop","title":"worktop: Edge-Native Web Framework","description":"worktop is a lightweight, high-performance web framework designed for edge computing environments. While originally focused on Cloudflare Workers, versions `0.8.0-next.x` are evolving towards platform agnosticism, supporting Cloudflare Workers, Service Workers (web), and Deno, with future plans for Node.js. The current stable release is `0.7.3`, but active development is ongoing in the `0.8.0-next` series, which introduces significant breaking changes and module restructuring to support its multi-runtime strategy. It differentiates itself by providing a minimal core API that adheres to Web Standards, offering a highly efficient router and specialized submodules for platform-specific features like KV storage and WebSockets, ensuring optimal performance in serverless and edge environments.","status":"active","version":"0.7.3","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/worktop","tags":["javascript","serviceworker","cloudflare","framework","workers","worker","http","api","typescript"],"install":[{"cmd":"npm install worktop","lang":"bash","label":"npm"},{"cmd":"yarn add worktop","lang":"bash","label":"yarn"},{"cmd":"pnpm add worktop","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM imports are standard. CommonJS `require` syntax is not supported in recent versions and edge runtimes.","wrong":"const { Router } = require('worktop')","symbol":"Router","correct":"import { Router } from 'worktop'"},{"note":"`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.","wrong":"import { start } from 'worktop/sw'","symbol":"listen","correct":"import { listen } from 'worktop'"},{"note":"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.","wrong":"import { KV } from 'worktop/kv'","symbol":"KV","correct":"import { KV } from 'worktop/cfw.kv'"}],"quickstart":{"code":"import { Router, listen } from 'worktop';\n\nconst API = new Router();\n\n// A basic GET endpoint\nAPI.add('GET', '/hello/:name', (request, context) => {\n  const name = context.params.name ?? 'World';\n  return new Response(`Hello, ${name}!`);\n});\n\n// A catch-all route for other paths or methods, serving static assets for Cloudflare Workers Pages\nAPI.add('GET', '/*', (request, context) => {\n  // For Cloudflare Workers Pages, `env.ASSETS.fetch` is used to serve static files.\n  // This assumes 'ASSETS' is bound in your wrangler.toml file.\n  // If not using Pages or static assets, this route would typically return a 404.\n  const url = new URL(request.url);\n  if (url.pathname.startsWith('/api')) {\n    // If the request was for an API route not matched above, return a 404\n    return new Response('Not Found', { status: 404 });\n  }\n  // Otherwise, attempt to serve a static asset if ASSETS binding exists\n  // This pattern is common when combining Worker API with static site hosting.\n  if (context.bindings && context.bindings.ASSETS) {\n    return context.bindings.ASSETS.fetch(request);\n  }\n  return new Response('Not Found', { status: 404 });\n});\n\n// Listen for incoming requests on the Workers environment\nlisten(API.handler);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0-next.10"},{"fix":"Update route definitions to reflect the new `regexparam` behavior. Access wildcard values using `context.params['*']` instead of `context.params.wild`.","message":"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 `'*'`.","severity":"breaking","affected_versions":">=0.8.0-next.18"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0-next.14"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.8.0-next.15"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: API.add is not a function"},{"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.","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.","error":"ReferenceError: structuredClone is not defined"},{"fix":"Access wildcard route parameters using `context.params['*']` instead of `context.params.wild`. For example, `const value = 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.","error":"The 'wild' parameter is not defined in context.params"}],"ecosystem":"npm"}