{"id":13473806,"url":"https://github.com/postlight/cloudflare-worker-app-kit","last_synced_at":"2025-06-10T14:40:17.898Z","repository":{"id":57137743,"uuid":"175291095","full_name":"postlight/cloudflare-worker-app-kit","owner":"postlight","description":"☁✨ A handy set of tools for creating a Cloudflare Worker app.","archived":false,"fork":false,"pushed_at":"2019-05-19T18:33:36.000Z","size":111,"stargazers_count":88,"open_issues_count":0,"forks_count":10,"subscribers_count":39,"default_branch":"master","last_synced_at":"2025-05-24T22:37:47.766Z","etag":null,"topics":["cloudflare","cloudflare-worker","eslint","jest","labs","server-side-rendering","starter-kit","typescript","webpack"],"latest_commit_sha":null,"homepage":"https://postlight.com/labs/cloudflare-worker-app-kit","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postlight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-12T20:26:24.000Z","updated_at":"2025-05-11T04:09:58.000Z","dependencies_parsed_at":"2022-08-22T20:50:16.204Z","dependency_job_id":null,"html_url":"https://github.com/postlight/cloudflare-worker-app-kit","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fcloudflare-worker-app-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fcloudflare-worker-app-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fcloudflare-worker-app-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fcloudflare-worker-app-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postlight","download_url":"https://codeload.github.com/postlight/cloudflare-worker-app-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postlight%2Fcloudflare-worker-app-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259093957,"owners_count":22804262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","cloudflare-worker","eslint","jest","labs","server-side-rendering","starter-kit","typescript","webpack"],"created_at":"2024-07-31T16:01:07.072Z","updated_at":"2025-06-10T14:40:17.870Z","avatar_url":"https://github.com/postlight.png","language":"JavaScript","funding_links":[],"categories":["Workers"],"sub_categories":["Tools"],"readme":"# Cloudflare Worker App Kit\n\n[Postlight](https://postlight.com)'s Cloudflare Worker App Kit is a handy set of tools for creating, developing, testing, and deploying a [Cloudflare Worker app](https://developers.cloudflare.com/workers/about/). No configuration, just build it and ship it. Read all about it in [this handy introduction](https://postlight.com/trackchanges/introducing-postlights-cloudflare-worker-app-kit).\n\n### Demo\n\nA real app built with these tools — [secretmsg.app](https://secretmsg.app) ([repo](https://github.com/postlight/secretmsg)).\n\n## Get started\n\n```bash\nnpx @postlight/cloudflare-worker-app-kit create \u003cAppName\u003e\n```\n\nThis `create` command scaffolds your project with the following:\n\n- [Project structure](#project-structure), including source files, so you can see how everything fits together.\n- [Development tools](#dev-tools) are all setup — local dev server, [TypeScript](https://www.typescriptlang.org/), webpack, [Prettier](https://prettier.io/), [ESLint](https://eslint.org/), and [Jest](https://jestjs.io/).\n- [Build and deploy](#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.\n\n## How the app works\n\nLike any server-side rendered app this runs in two environments — [client](src/client.ts) and [worker](src/worker.ts). The client entry point is typical of most single-page, JavaScript applications. The root component is rendered into a container on the page, and in this case, nothing happens since the page was delivered fully-rendered.\n\nThe worker entry point is where things are a little different.\nInstead of sending the request all the way back to a Node.js server running in a central location, a quick-to-start Worker sitting in front of Cloudflare's cache handles the request. If it's a request for a static asset, like an image or JavaScript file, we fetch it from the cache or S3 like we normally would. If it's for a page, we render the app, delivering all the html. With all this happening at the edge, your user gets great response times no matter where they're located.\n\nThat'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!\n\n### Project structure\n\n```\n# Static assets will be copied to S3 and served by the worker\nassets/\n └─ images/\n\n# Scripts for build, deploy, and the dev server\nscripts/\n ├─ build.js\n ├─ deploy.js\n └─ start.js\n\n# App files\nsrc/\n ├─ components/\n ├─ lib/\n ├─ client.ts\n └─ worker.ts\n```\n\nAfter 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.\n\n### Environment variables\n\nThese environment variables are required to deploy the app. If you're not sure where to find these values, there's [more info below](#setup-cloudflare-and-s3).\n\n```bash\nBUCKET=bucket-name\nAWS_KEY=XXXACCESSKEYXXX\nAWS_SECRET=XXXXXXXXXSECRETXXXXXXXXX\nAWS_REGION=us-east-1\nCF_ZONE_ID=XXXXXXXXXWORKERZONEIDXXXXXXXXX\nCF_KEY=XXXXCLOUDFLAREAUTHKEYXXXX\nCF_EMAIL=account@email.com\n```\n\nIf you want to use [Workers KV](https://developers.cloudflare.com/workers/kv/) you'll need the `CF_KV_NAMESPACES` environment variable during development and when you deploy.\n\n```bash\n# single KV namespace\nCF_KV_NAMESPACES=\"NAME XXXXXXXXXNAMESPACEIDXXXXXXXXX\"\n\n# multiple namespace are supported, separate with a comma\nCF_KV_NAMESPACES=\"NS_1 XXXXXXXNAMESPACEIDXXXXXXX, NS_2 XXXXXXXNAMESPACEIDXXXXXXX\"\n```\n\nSimilarly, you can bind other strings with `CF_WORKER_BINDINGS`\n\n```bash\nCF_WORKER_BINDINGS=\"KEY_1 value1, KEY_2 value2\"\n```\n\n### Dev tools\n\nThe local dev environment consists of two servers. One delivers static assets using [webpack middleware](https://github.com/webpack/webpack-dev-middleware), basically standing in for S3. The other wraps [Cloudworker](https://github.com/dollarshaveclub/cloudworker) — a mock implementation of Cloudflare Workers. It loads the worker.js bundle and handles requests just like a worker would.\n\n```bash\n# Start a dev server at http://localhost:3333\nnpm start\n```\n\nColocate test files with your source files with a `.test.ts` extension, and Jest will do the rest.\n\n```bash\n# Run jest tests\nnpm test\n```\n\nYou know the drill, ESlint is here to keep you honest.\n\n```bash\n# Check source files for common errors\nnpm run lint\n```\n\n### Build and deploy\n\nUsing 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.\n\n```bash\n# Output production-ready JS \u0026 CSS bundles in dist folder\nnpm run build\n```\n\nFirst, 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.\n\n```bash\n# Build files, copy static assets to S3, and deploy worker to Cloudflare\nnpm run deploy\n```\n\n## Setup Cloudflare and S3\n\nTwo 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.\n\n### Cloudflare\n\n1. If you don't have a domain setup with Cloudflare, [step 2](https://support.cloudflare.com/hc/en-us/articles/201720164-Step-2-Create-a-Cloudflare-account-and-add-a-website) and [step 3](https://support.cloudflare.com/hc/en-us/articles/205195708) of their [_Getting Started_](https://support.cloudflare.com/hc/en-us/categories/200275218-Getting-Started) guide is a good place to start.\n2. [Visit your Cloudflare dashboard](https://dash.cloudflare.com/) to turn on workers.\n3. 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](https://api.cloudflare.com/#worker-filters-create-filter).\n4. 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.\n5. Before finishing, now's a good time to gather some environment variable values — `CF_ZONE_ID` and `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**.\n\n### AWS S3\n\nOne 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](https://medium.freecodecamp.org/how-to-host-a-website-on-s3-without-getting-lost-in-the-sea-e2b82aa6cd38).\n\nYou 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](https://developers.cloudflare.com/workers/recipes/static-site/).\n\nWhile setting up your bucket, you should also gather some environment variable values for `BUCKET`, `AWS_KEY`, `AWS_SECRET`, and `AWS_REGION`. For the AWS credentials you should setup a user with [read and write access](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_s3_rw-bucket-console.html) to the new bucket.\n\n---\n\n🔬 A Labs project from your friends at [Postlight](https://postlight.com). Happy coding!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fcloudflare-worker-app-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostlight%2Fcloudflare-worker-app-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostlight%2Fcloudflare-worker-app-kit/lists"}