In this post, we showcase how Cloudflare Workers can be easily tested locally in the LocalStack platform, using our novel LocalStack Extensions mechanism.
LocalStack is a cloud service emulator that can run in a single container on your local machine or in your CI environment, which lets you run your cloud and serverless applications without connecting to an AWS account. Please check out the Getting Started guide in the LocalStack documentation for more information.
With version 1.0 of LocalStack, we have introduced Extensions that allow developers to extend and customize LocalStack. You can use Extensions to add new services, extend existing services, and even add custom functionality.
Below is a simple example extension called MyExtension, which illustrates the different lifecycle hooks, and how they relate to the request processing inside your LocalStack instance. One of the extension hooks is
update_gateway_routes(..) which allows adding custom HTTP routes to the request processing middleware of the LocalStack Gateway Router. It allows us to add arbitrary API endpoints to LocalStack, accessible through the canonical edge port
4566, i.e., under
While Miniflare is great, it only covers a subset of the functionality required for full local testing. Most importantly, Miniflare allows to start of Cloudflare Workers in a local development server (e.g., running on
http://localhost:8787), but it does not emulate the actual Cloudflare API used to create users, services, deployments, etc.
Ideally, we would like to test the full workflow end-to-end in a local environment that mimics the production system. For example, one of the main tools to develop Cloudflare Workers is wrangler, a framework and CLI that simplifies the development and deployment of Workers. Below is a simple CLI example that illustrates how to create a sample app via an interactive wizard (
wrangler init) and then deploy the application to the Cloudflare production environment (
# create demo application in local directory $ wrangler init ... # publish application to Cloudflare $ wrangler publish ...
Wouldn’t it be great to run the production
wrangler commands against an emulator to facilitate local testing? This is where the Cloudflare LocalStack Extension comes into play!
The Cloudflare LocalStack Extension uses the
update_gateway_routes(..) extension lifecycle hook to define an additional endpoint
http://localhost:4566/miniflare that is served directly inside the LocalStack instance. Note that the extension provides more functionality than the
miniflare emulator - we also provide a (very simplistic) emulated/mocked version of the Cloudflare API, which allows users to create local services, script uploads, deployments, etc.
Upon local deployment via the
wrangler CLI, the extension receives the deployment requests under the
/cloudflare/... endpoint. It then starts the
miniflare process inside the LocalStack container and makes it accessible under a new local endpoint like
w1.cloudflare.localhost.localstack.cloud (this domain name resolves to
127.0.0.1). The client can now use this endpoint to invoke the deployed Worker via the Web browser or an HTTP client like
To install the extension, make sure you have LocalStack Pro running (you can get a free trial API key) and the latest version of the
localstack CLI installed - then the extension can be installed via the following command:
$ localstack extensions install "git+https://github.com/localstack/localstack-extensions/#egg=localstack-extension-miniflare&subdirectory=miniflare"
To use the extension, we can simply use the
wrangler CLI after exporting the relevant environment variables
CLOUDFLARE_API_TOKEN, which cause
wrangler to run the deployment requests against the LocalStack extension.
$ export CLOUDFLARE_API_BASE_URL=http://localhost:4566/miniflare $ export CLOUDFLARE_API_TOKEN=test $ wrangler publish ... > email@example.com deploy > wrangler publish ⛅️ wrangler 2.6.2 ------------------- Total Upload: 0.21 KiB / gzip: 0.18 KiB Uploaded hello (0.05 sec) Published hello (3.03 sec) Current Deployment ID: bcf48806-b317-4351-9ee7-36e7d557d4de
Once deployed, the Cloudflare worker can be easily invoked via
$ curl http://hello.miniflare.localhost.localstack.cloud:4566/test Hello World!
In this short post, we have demonstrated how to easily test Cloudflare Worker applications locally using the LocalStack Cloudflare Extension. The scope of this extension goes beyond the capabilities of
miniflare. In addition to serving the Workers, it also provides a (very simple) emulated version of the actual Cloudflare API, allowing us to use production tools like
wrangler to develop, deploy, and test our Workers applications locally.
At LocalStack, we continue to invest in our Extensions mechanism and provide emulators that go beyond our core scope of running AWS apps locally - aiming to become the go-to platform for running emulators for any kind of API or managed service out there!
We would love to hear your thoughts, and whether you have ideas for new LocalStack Extensions we could develop - looking forward to getting your feedback!