Cloudworker  -  A local Cloudflare Worker Runner

This is a guest post by Hank Jacobs, who is the Lead Software Engineer for Platform Services & Tools at Dollar Shave Club. This post originally appeared on the DSC Engineering blog.

At Dollar Shave Club, we continuously look for ways to improve how we build and ship code. Improving the time it takes for engineers to ship code is key. Providing engineers with a development environment that closely mirrors production really helps.

Earlier this year, we began evaluating Cloudflare Workers as a replacement for our legacy edge routing and caching layers. Cloudflare Workers brings the power of Javascript to Cloudflare’s Edge. Developers can write and deploy Javacript that gets executed for every HTTP request that passes through Cloudflare. This capability excited us but a critical thing was missing — a way to run Worker code locally. We couldn’t find a suitable solution, so we started to build our own. Luckily, Workers uses the open Service Workers API so we had documentation to consult. Within a few weeks, Cloudworker was born.

Cloudworker

Cloudworker is a local Cloudflare Worker runtime. With it, you can run Cloudflare Worker scripts locally (or anywhere you can run a Docker image). Our primary goal with Cloudworker is to be as compatible with Cloudflare Workers as possible, simulating features where we can and stubbing out features otherwise.

Getting Started

To use Cloudworker, install it using npm.

npm install -g @dollarshaveclub/cloudworker

Using it is straightfoward.

cloudworker <worker script>

See the readme for a complete list of supported flags.

WebAssembly

Cloudflare Workers supports the direct execution of WebAssembly, and so does Cloudworker.

To start using WebAssembly, run Cloudworker with the --wasm flag to bind a Javascript variable to your .wasm file:

cloudworker --wasm Wasm=module.wasm worker.js

From within your worker script, you can now create a new WebAssembly Instance with the bound variable.

addEventListener('fetch', event => {
  const instance = new WebAssembly.Instance(Wasm)
  instance.exports.exported_func()
  event.respondWith(new Response('Success!'))
})

See the WebAssembly section of the readme for more examples.

Workers KV

Cloudworker also supports an in-memory version of the beta Workers KVfeature of Cloudflare Workers. Workers KV is key-value store that can be accessed by Worker scripts.

Key-value pairs can be bound to a variable using the --set flag.

cloudworker --set Store.hello=world worker.js

Those key-value pairs can then be used within the worker script.

addEventListener('fetch', async event => {  
  const value = await Store.get('hello')    
  event.respondWith(new Response(value)) // Responds with 'world'
})

Closing Thoughts

Since its initial release, Cloudworker has become an integral part of our Cloudflare Worker development workflow. We use it to develop our edge router locally as well as use it within our on-demand QA environments. Additionally, we’ve used Cloudworker as a platform for an internal proxy used to reduce the footprint of our QA environments. We’re truly excited about Cloudworker and hope you find it as useful as we have!

Cloudflare editor's note: We love seeing all of the projects the Cloudflare Workers community creates! While we can't post about everything on the blog, it helps others out when you share what you've built on community.cloudflare.com and Twitter. Some examples of other community projects are:

• Cloudflare Worker Local (another approach to testing Workers locally)
• Cloudflare Workers KV UI Explorer