cloudflare-worker-local

Run (or test) a Cloudflare Worker Locally. If you are looking for a project that will quickly help you bootstrap your worker, take a look at create-cloudflare-worker

Running

$ npm install -g cloudflare-worker-local
$ cloudflare-worker-local /path/to/worker.js localhost:3000 4000

Listening on Port 4000 and forwarding requests to http://localhost:3000/

Automatically reloading

It is possible to use nodemon to automatically reload the worker

$ npm install -g nodemon
$ nodemon --watch /path/to/worker.js --signal SIGHUP --exec 'cloudflare-worker-local /path/to/worker.js localhost:3000 4000'

Unit Testing a Cloudflare Worker

cloudflare-worker-local can be used to unit test a cloudflare worker. Please see This Example. You may also be interested in create-cloudflare-worker

Things that are supported (and in scope)

• Anything in Node.js scope by default (Object, Array)
• Anything provided by fetch (fetch, Request, Response, Headers)
• WHATWG URL
• console
• btoa / atob
• crypto.subtle
• Cloudflare key value store if you pass in the KV_NAMESPACE environment variable
• Cloudflare event.passThroughOnException() for runtime exception handling
• Cloudflare Environment Variables and Secrets loaded from a wrangler.toml
• Workers Sites
• Set cloudflare CF-IPCountry header value from COUNTRY environment variable (default is DEV)
• ... this list should probably have more things

Contributors

• Tejas Dinkar (@gja)
• Jeremy Danyow (@jdanyow)
• Rita Liu (@rita-liu)
• Nolan Woods (@innovate-invent)
• Brendan Coll (@mrbbot)

Future enhancements

• Support WASM
• Support CPU timeouts
• Better Examples

Environment Variables

• NUM_WORKERS - Specifies the number of node workers (default 1, to get KV Working in memory)
• KV_NAMESPACES - A comma separated list of keyspaces. (ex: MY_STORE,ANOTHER_STORE)

CloudFlare KV Store emulation using Minio or any S3 compatible service

To enable Minio as the KV store simply provide these options as environment variables: MINIO_ENDPOINT, MINIO_ACCESS_KEY, and MINIO_SECRET_KEY

$ MINIO_ENDPOINT="localhost" MINIO_ACCESS_KEY="my_access_key" MINIO_SECRET_KEY="my_secret" cloudflare-worker-local /path/to/worker.js localhost:3000 4000

Optionally, these variables are available as well: MINIO_PORT, MINIO_USE_SSL, MINIO_REGION, MINIO_TRANSPORT, MINIO_SESSIONTOKEN, and MINIO_PARTSIZE

See the Minio documentation for details on the various parameters.

CloudFlare KV Store emulation using the File System

To use the File System as the KV store simply provide the KV_FILE_ROOT option as an environment variable. A directory will be created in here for each KV namespace.

CloudFlare Environment Variables and Secrets

Support for CloudFlare Environment Variables and Secrets is provided via a wrangler.toml file. See the wrangler documentation for more information on the file schema.

To load the wrangler.toml, specify it on the command line:

$ cloudflare-worker-local /path/to/worker.js localhost:3000 4000 /path/to/wrangler.toml

Optionally, the desired environment specified within the wrangler.toml can be loaded:

$ cloudflare-worker-local /path/to/worker.js localhost:3000 4000 /path/to/wrangler.toml production

Secrets are specified under the 'secrets' root key in the document. See the wrangler.toml for an example of the supported structures.

Two features are provided while loading the wrangler.toml:

• All vars and secrets strings can contain ${} placeholders. A placeholder path is resolved using lodash.get and has the context of the root of the config document. A placeholder can not refer to a value defined later in the document that also has placeholders.
• Any var or secret that is not a string will be automatically JSON encoded. This allows you to inject complex data into a script by JSON decoding the variable value.

Additionally, any 'kv-namespaces' in the wrangler.toml will be appended to the list of namespaces provided by KV_NAMESPACES.

Workers Sites

If a wrangler.toml file containing a [site] section with a bucket directory is loaded, the Workers Sites default KV namespace and manifest will be added to the worker's scope. Calls to getAssetFromKV will always return the latest version of an asset in the bucket directory. Note that you'll need to bundle your worker code (with Webpack for instance) before running it to use @cloudflare/kv-asset-handler, as import/ require are not in workers' scopes.