Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gja/cloudflare-worker-local
Run a Cloudflare Worker Locally
https://github.com/gja/cloudflare-worker-local
Last synced: 13 days ago
JSON representation
Run a Cloudflare Worker Locally
- Host: GitHub
- URL: https://github.com/gja/cloudflare-worker-local
- Owner: gja
- License: apache-2.0
- Created: 2018-11-13T20:38:14.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T19:16:19.000Z (7 months ago)
- Last Synced: 2024-10-02T07:59:06.950Z (about 1 month ago)
- Language: JavaScript
- Size: 1.38 MB
- Stars: 175
- Watchers: 7
- Forks: 39
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - cloudflare-worker-local
README
# 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](https://github.com/gja/create-cloudflare-worker)
## Running
```shell
$ 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
```shell
$ 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](examples/unit-test-a-worker). You may also be interested in [create-cloudflare-worker](https://github.com/gja/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()](https://workers.cloudflare.com/docs/reference/workers-concepts/fetch-event-lifecycle/#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
```shell script
$ 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](https://docs.min.io/docs/javascript-client-api-reference.html) 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](https://developers.cloudflare.com/workers/tooling/wrangler/configuration)
for more information on the file schema.
To load the wrangler.toml, specify it on the command line:
```shell
$ 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:
```shell
$ 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](./examples/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.