Cloudflare Worker App Kit
Postlight's Cloudflare Worker App Kit is a handy set of tools for creating, developing, testing, and deploying a Cloudflare Worker app. No configuration, just build it and ship it. Read all about it in this handy introduction.
npx @postlight/cloudflare-worker-app-kit create <AppName>
create command scaffolds your project with the following:
- Project structure, including source files, so you can see how everything fits together.
- Development tools are all setup — local dev server, TypeScript, webpack, Prettier, ESLint, and Jest.
- Build and deploy scripts. Provide the necessary environment variables and run the commands to ship your app to Cloudflare's 150+ locations around the world.
How the app works
That's it, no origin server to worry about. Just some files on S3 and a little JS distributed around the world. The result is a fast, server-rendered web app that can handle 10 million requests per month for $5 — not bad!
# Static assets will be copied to S3 and served by the worker assets/ └─ images/ # Scripts for build, deploy, and the dev server scripts/ ├─ build.js ├─ deploy.js └─ start.js # App files src/ ├─ components/ ├─ lib/ ├─ client.ts └─ worker.ts
After you build the app there will also be
dist directory where you'll find JS and CSS bundles along with their associated source maps. During deploys those files get copied to S3 along with your other assets.
These environment variables are required to deploy the app. If you're not sure where to find these values, there's more info below.
BUCKET=bucket-name AWS_KEY=XXXACCESSKEYXXX AWS_SECRET=XXXXXXXXXSECRETXXXXXXXXX AWS_REGION=us-east-1 CF_ZONE_ID=XXXXXXXXXWORKERZONEIDXXXXXXXXX CF_KEY=XXXXCLOUDFLAREAUTHKEYXXXX CF_EMAILfirstname.lastname@example.org
If you want to use Workers KV you'll need the
CF_KV_NAMESPACES environment variable during development and when you deploy.
# single KV namespace CF_KV_NAMESPACES="NAME XXXXXXXXXNAMESPACEIDXXXXXXXXX" # multiple namespace are supported, separate with a comma CF_KV_NAMESPACES="NS_1 XXXXXXXNAMESPACEIDXXXXXXX, NS_2 XXXXXXXNAMESPACEIDXXXXXXX"
Similarly, you can bind other strings with
CF_WORKER_BINDINGS="KEY_1 value1, KEY_2 value2"
The local dev environment consists of two servers. One delivers static assets using webpack middleware, basically standing in for S3. The other wraps Cloudworker — a mock implementation of Cloudflare Workers. It loads the worker.js bundle and handles requests just like a worker would.
# Start a dev server at http://localhost:3333 npm start
Colocate test files with your source files with a
.test.ts extension, and Jest will do the rest.
# Run jest tests npm test
You know the drill, ESlint is here to keep you honest.
# Check source files for common errors npm run lint
Build and deploy
Using webpack, this script creates production-ready bundles for the client, worker and any css you imported into you components. If you're going to use the
deploy script below, don't worry about this. It will run its own fresh build anyway.
# Output production-ready JS & CSS bundles in dist folder npm run build
First, dependencies are installed and a fresh build is made. Then all the static files are copied to your S3 bucket Finally, the new worker script, along with some metadata, is deployed to Cloudflare.
# Build files, copy static assets to S3, and deploy worker to Cloudflare npm run deploy
Setup Cloudflare and S3
Two things need to happen before you can deploy. Get Cloudflare in front of your domain and setup an S3 bucket to serve static files to the public.
- If you don't have a domain setup with Cloudflare, step 2 and step 3 of their Getting Started guide is a good place to start.
- Visit your Cloudflare dashboard to turn on workers.
- In the Workers tab, launch the workers editor then go to the routes section on the left. These routes filter what requests will be handled by the worker, something like
example.net/*is a good place to start. All requests to your domain will go through the worker. If you're familiar with curl, you can do all of this from the command-line.
- If you want to play with the worker editor, it's a nice way to see some immediate results. There are also some handy debugging tools that might be helpful later on.
- Before finishing, now's a good time to gather some environment variable values —
CF_KEY. Zone ID is on the dashboard overview page in the right column. For the API key, visit your user profile page, scroll to the bottom and copy the Global API Key.
One way to handle this is to treat your S3 bucket like a static web server. You give it a name that matches your domain, like
example.net and change your Cloudflare DNS settings to point at that bucket. If you haven't done this before, here's a good step-by-step explanation.
You can also name the bucket anything you want, leaving the DNS settings alone. You would then handle all the routing in the worker, like this.
While setting up your bucket, you should also gather some environment variable values for
AWS_REGION. For the AWS credentials you should setup a user with read and write access to the new bucket.