diff --git a/README.md b/README.md index bb8c822..788db48 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,5 @@ # Cloudflare Workers Router ---- -### **PRE-RELEASE** - -**This branch is only for use with [wrangler2](https://github.com/cloudflare/wrangler2) and might also not work reliably!** - -**USE AT YOUR OWN RISK!** - -See [Migration Guide](https://github.com/tsndr/cloudflare-worker-router/blob/v2-pre/MIGRATION.md) - ---- - - Cloudflare Workers Router is a super lightweight router (2.30 KiB) with middleware support and **ZERO dependencies** for [Cloudflare Workers](https://workers.cloudflare.com/). When I was trying out Cloudflare Workers I almost immediately noticed how fast it was compared to other serverless offerings. So I wanted to build a full-fledged API to see how it performs doing real work, but since I wasn't able to find a router that suited my needs I created my own. @@ -100,7 +88,7 @@ export default { ## Reference -### `router.debug([state])` +### `router.debug([state = true])` Enable or disable debug mode. Which will return the `error.stack` in case of an exception instead of and empty `500` response. Debug mode is disabled by default. @@ -109,15 +97,18 @@ Enable or disable debug mode. Which will return the `error.stack` in case of an State is a `boolean` which determines if debug mode should be enabled or not (default: `true`) -### `router.use(handler)` +### `router.use([...handlers])` Register a global middleware handler. -#### `handler` (function) +#### `handler(ctx)` Handler is a `function` which will be called for every request. +#### `ctx` +Object containing `env`, [`req`](#req-object), [`res`](#res-object), `next` + ### `router.cors([config])` @@ -189,34 +180,71 @@ Key | Type | Description ## Setup -### Wrangler2 +--- +### ❗️ Compatibility ❗️ -You can use [wrangler2](https://github.com/cloudflare/wrangler2) to generate a new Cloudflare Workers project based on this router by running the following command from your terminal: +CLI Tool | Router +-------- | ------ +[wrangler2](https://github.com/cloudflare/wrangler2#readme) | Use `v2.x.x` or later. +[@cloudflare/wrangler](https://github.com/cloudflare/wrangler#readme) | Use `v1.x.x`, [here](https://github.com/tsndr/cloudflare-worker-router/tree/v1#readme). -// TODO: Needs update! -``` -wrangler generate myapp https://github.com/tsndr/cloudflare-worker-router-template +See [Migration from v1.x.x to v2.x.x](https://github.com/tsndr/cloudflare-worker-router/blob/v2-pre/MIGRATION.md) if you want to update. + +--- + +### **[Wrangler2](https://github.com/cloudflare/wrangler2#readme)** + +Please follow Cloudflare's [Get started guide](https://developers.cloudflare.com/workers/get-started/guide/), then install the router using this command + +```bash +npm i -D @tsndr/cloudflare-worker-router@pre ``` -Before publishing your code you need to edit `wrangler.toml` file and add your Cloudflare `account_id` - more information about publishing your code can be found [in the documentation](https://developers.cloudflare.com/workers/learning/getting-started). +and replace your `index.ts` / `index.js` with one of the following scripts -Once you are ready, you can publish your code by running the following command: +
+TypeScript (src/index.ts) +```typescript +import Router from '@tsndr/cloudflare-worker-router' + +export interface Env { + // Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/ + // MY_KV_NAMESPACE: KVNamespace; + // + // Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/ + // MY_DURABLE_OBJECT: DurableObjectNamespace; + // + // Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/ + // MY_BUCKET: R2Bucket; +} + +const router = new Router() + +// TODO: add your routes here + +export default { + async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { + return router.handle(env, request) + } +} ``` -wrangler publish +
+ +
+JavaScript (src/index.js) + +```javascript +import Router from '@tsndr/cloudflare-worker-router' + +const router = new Router() + +// TODO: add your routes here + +export default { + async fetch(request, env, ctx) { + return router.handle(env, request) + } +} ``` - -You can also test it loacally by running the following command: - -``` -wrangler dev -``` - - -### npm - -If you already have a wrangler project you can install the router like this: - -``` -npm i @tsndr/cloudflare-worker-router@pre -``` \ No newline at end of file +
\ No newline at end of file