Registry / web-framework / worktop

worktop

JSON →
library0.7.3jsnpmunverified

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.

npm install worktop
INSTALL
IMPORT
SIG · WORKTOP
W
worktop
web-frameworkjavascriptv0.7.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Router
✓ import { Router } from 'worktop'
✗ const { Router } = require('worktop')
ESM imports are standard. CommonJS `require` syntax is not supported in recent versions and edge runtimes.
listen
✓ import { listen } from 'worktop'
✗ import { start } from 'worktop/sw'
`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
✓ import { KV } from 'worktop/cfw.kv'
✗ import { KV } from 'worktop/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.

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);
Debug
Known issues
breakingThe `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.
affects: >=0.8.0-next.10
breakingThe 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`.
affects: >=0.8.0-next.18
breakingThe `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.
affects: >=0.8.0-next.14
gotchaTypeScript 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.
affects: <0.8.0-next.15
Errors
Common errors & fixes
TypeError: API.add is not a function
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
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
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['*']`.
Upgrade
Version history
0.7.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
24
OpenAI (training)
1
Resources
worktop — npm install worktop · libregistry