{"id":13719648,"url":"https://github.com/Girish21/remix-cloudflare-workers-template","last_synced_at":"2025-05-07T11:32:32.728Z","repository":{"id":37525527,"uuid":"495014933","full_name":"Girish21/remix-cloudflare-workers-template","owner":"Girish21","description":"A starter template for Remix + Cloudflare Workers + DO + KV + Turborepo","archived":false,"fork":false,"pushed_at":"2023-04-09T07:18:05.000Z","size":1075,"stargazers_count":63,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-14T09:38:59.717Z","etag":null,"topics":["cloudflare","cloudflare-workers","durable-objects","kv","remix","remix-run","remix-stack","turborepo","typescript"],"latest_commit_sha":null,"homepage":"https://remix.run/docs/en/v1/pages/stacks","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Girish21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-22T09:31:56.000Z","updated_at":"2024-11-04T02:36:06.000Z","dependencies_parsed_at":"2024-11-14T09:31:18.000Z","dependency_job_id":null,"html_url":"https://github.com/Girish21/remix-cloudflare-workers-template","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Girish21%2Fremix-cloudflare-workers-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Girish21%2Fremix-cloudflare-workers-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Girish21%2Fremix-cloudflare-workers-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Girish21%2Fremix-cloudflare-workers-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Girish21","download_url":"https://codeload.github.com/Girish21/remix-cloudflare-workers-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252869146,"owners_count":21816983,"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-workers","durable-objects","kv","remix","remix-run","remix-stack","turborepo","typescript"],"created_at":"2024-08-03T01:00:53.498Z","updated_at":"2025-05-07T11:32:27.854Z","avatar_url":"https://github.com/Girish21.png","language":"TypeScript","funding_links":[],"categories":["Starter"],"sub_categories":[],"readme":"# Remix + Cloudflare Workers starter with Turborepo 🚀\n\nStarter to get going with Remix and Cloudflare Workers.\n\nThis template is based on the starter created by [Jacob](https://github.com/jacob-ebey)([remix-cloudflare-worker-template](https://github.com/jacob-ebey/remix-cloudflare-worker-template/)).\n\n## What's inside? 👀\n\nThis turborepo uses [npm](https://www.npmjs.com/) as a package manager. It includes the following packages/apps:\n\n### Apps and Packages 📦\n\n- `counter-do`: a [Durable Object](https://developers.cloudflare.com/workers/runtime-apis/durable-objects) class for managing the count state\n- `remix-app`: a [Remix](https://remix.run) app (with Tailwind)\n- `worker`: a [Worker](https://developers.cloudflare.com/workers) handler function\n- `cloudflare-env`: types for Cloudflare environement variables\n- `eslint-config-custom`: `eslint` configurations (includes `@remix-run/eslint-config` and `eslint-config-prettier`)\n- `tsconfig`: `tsconfig.json` used throughout the monorepo\n\n## Getting Started 🪄\n\nLet's setup `wrangler` CLI [instalation](https://github.com/cloudflare/wrangler#installation) (wrangler requires a minimum Node version of `16`)\n\n```sh\nnpm i @cloudflare/wrangler -g\n```\n\nAfter installation, log in to your Cloudflare account from the CLI.\n\n```sh\nwrangler login\n```\n\nLet's install the dependencies.\n\n```sh\nnpm install\n```\n\nNow we can set up the project.\n\n```sh\nnpm run setup\n```\n\nThe setup script will ask for your worker's name. It can be any name. And then, we also need to add the Account ID, which you can find by visiting the Cloudflare [Dashboard](https://dash.cloudflare.com).\n\nYou can add the Worker name and the Account ID later to the [`wrangler.toml](packages/worker/wrangler.toml).\n\nThat's all we're ready to push to prod! 🚀\n\nBefore pushing to the worker via GitHub action, we have to configure the `CF_API_TOKEN` secret in GitHub. We can generate an API Token from [here](https://dash.cloudflare.com/profile/api-tokens). When presented with the list of templates to choose from, select the \"Edit Cloudflare Workers\" option. This template should have the necessary permissions to push a Worker from GitHub. Now we can commit the changes made to `wrangler.toml` and push the changes.\n\n```sh\ngit commit -am \"\u003cmessage\u003e\"\ngit push\n```\n\n### Recap 🌀\n\n```sh\nnpm install @cloudflare/wrangler -g\nwrangler login\nnpm install\nnpm run setup\n# configure CF_API_TOKEN action secret\ngit add -A -m \"\u003cmessage\u003e\"\ngit push\n```\n\n## Durable Objects 🔥\n\nDurable Objects are only available with a Workers paid subscription. However, you can upgrade to the paid plan from the [Dashboard](https://dash.cloudflare.com).\n\nThis starter template comes with a simple DO implementation to keep track of the number of times the root loader is invoked.\n\nIf you're starting with DO and not sure what it is, go through the official docs on [Durable Objects](https://developers.cloudflare.com/workers/runtime-apis/durable-objects/) will be a good start! And checkout [using durable objects](https://developers.cloudflare.com/workers/learning/using-durable-objects/) for more applications of DO.\n\n### Defining a Durable Object\n\nThis template comes with a script to create the boilerplate for a new Durable Object class.\n\n```sh\nnpm run new:do\n```\n\nThe script will have instructions to initialise the DO with the worker. Don't forget to follow them!\n\n#### More information on DO\n\n\u003e You can skip this section if you have used the script to generate the DO class. Continue for more information on DO :)\n\nTo define a DO class, check out the [docs](https://developers.cloudflare.com/workers/runtime-apis/durable-objects/#durable-object-class-definition).\n\nTo include the DO class into the worker, we have to add the new DO package as a `dependendency` of the [`worker`](packages/worker/package.json). Then we need to create a binding for the DO in the configuration file [`wrangler.toml`](packages/worker/wrangler.toml).\n\n```toml\n[durable_objects]\nbindings = [\n  {name = \"\u003cDO_BINDING_NAME\u003e\", class_name = \"\u003cDO_CLASS_NAME\u003e\"},\n]\n```\n\nFor development add the following to [`wrangler.dev.toml`](packages/worker/wrangler.dev.toml)\n\n```toml\n[env.dev.durable_objects]\nbindings = [\n  {name = \"\u003cDO_BINDING_NAME\u003e\", class_name = \"\u003cDO_CLASS_NAME\u003e\"},\n]\n```\n\nWe must create a [migration](https://developers.cloudflare.com/workers/learning/using-durable-objects/#durable-object-migrations-in-wranglertoml) to register the DO in the configuration file.\n\n```toml\n[[migrations]]\ntag = \"v\u003cRUNNING_TAG_ID\u003e\"\nnew_classes = [\"\u003cDO_CLASS_NAME\u003e\"]\n```\n\nMore info about uploading a DO [here](https://developers.cloudflare.com/workers/learning/using-durable-objects/#uploading-a-durable-object-worker).\n\nThe DO binding will be available in the data functions (`loader`/`action`) through the `context` argument. Types for the `context` can be added at [cloudflare-env](./config/cloudflare-env/index.d.ts). To add a type for a newly created DO, we have to add the following to the `.d.ts` file\n\n```ts\n\u003cDO_BINDING_NAME\u003e: DurableObjectNamespace\n```\n\nNow we can access the DO binding from the data function through the `context`.\n\n```ts\nexport let loader: LoaderFunction = ({ context }) =\u003e {\n  context.MY_DO\n  //        ^ Will have proper type definitions\n  return null\n}\n```\n\n### Deleting a DO\n\nIt requires a migration to delete a DO. More info [here](https://developers.cloudflare.com/workers/learning/using-durable-objects/#durable-object-migrations-in-wranglertoml)\n\n## Worker KV 📒\n\n- [KV](https://developers.cloudflare.com/workers/runtime-apis/kv/)\n- [Wrangler KV CLI](https://developers.cloudflare.com/workers/wrangler/workers-kv/)\n\nThis template does not come with a KV namespace attached to it. However, you can create one using the Wrangler CLI.\n\n```sh\nwrangler kv:namespace create \"MY_KV\"\n```\n\nThe above command will create a KV namespace. Now we need to bind the created namespace with the worker. When we run the create command, the CLI will print the binding configuration we need to add to our `wrangler.toml` configuration file. It will look like\n\n```toml\nkv_namespaces = [\n  { binding = \"MY_KV\", id = \"xxxx\" }\n]\n```\n\nWe must add this above the `[site]` block in the `wrangler.toml` file.\n\nWe have added the KV namespace binding for the production environment, but we also need a namespace for `dev`. We can do that by creating a new namespace for `dev`.\n\n```sh\nwrangler kv:namespace create \"MY_KV\" --preview\n```\n\nThis will generate a namespace for the `dev` environment, and we must add this below the `[env.dev]` block in the dev configuration file `wrangler.dev.toml`.\n\n```toml\n[env.dev]\nkv_namespaces = [\n  { binding = \"MY_KV\", id = \"xxxx\", preview_id = \"xxxx\" }\n]\n```\n\n**Note**: We need to add the `preview_id` key to the configuration file along with the `id` key with the same value (ref: [stackoverflow](https://stackoverflow.com/a/71898353/17459282)).\n\nThe bounded KV will be available in the `loader`/`action` via the `context` argument passed to the functions. We define types for the `context` at [cloudflare-env](./config/cloudflare-env/index.d.ts). To add types for a newly bounded KV, we have to add the following to the `.d.ts` file\n\n```ts\nMY_KV: KVNamespace\n```\n\nNow we can access the KV namespace from the data function through the `context`.\n\n```ts\nexport let loader: LoaderFunction = ({ context }) =\u003e {\n  context.MY_KV\n  //        ^ Will have proper type definitions\n  return null\n}\n```\n\n## Environment Variables (Secrets) 🔐\n\n### Adding Worker Environment Variables\n\nYou must run `wrangler` commands from a directory which contains the `wrangler.toml` file. Either we can `cd` into the worker directory present at `packages/worker`, or we can specify the path to the configuration file in the CLI.\n\nTo set a worker `secret`, we can\n\n```sh\ncd packages/worker\nwrangler secret put \u003cSECRET_NAME\u003e\n```\n\nor,\n\n```sh\nwrangler secret -c packages/worker/wrangler.toml\n```\n\nLike DO/KV binding, the Env variables will be passed to the data functions via the `context` argument. But we have only configured the production worker with the secret. So let's configure the local environment with the secret.\n\nWhen we ran `npm run setup`, the CLI would have created `packages/worker/wrangler.dev.toml`. And the configuration file should have a `vars` key under the `[env.dev]` table. So we can add the new secret there.\n\n```toml\n[env.dev]\nvars = {SECRET_KEY = \"\u003cvalue\u003e\"}\n```\n\nOne last thing to do is add the type definition for the Env var at `config/cloudflare-env/index.d.ts`.\n\n```ts\nSECRET_KEY: string\n```\n\nNow, we can access SESSION_SECRET via `context.env.SESSION_SECRET` in the data functions inside our Remix app.\n\n## Turbo Setup ✨\n\nThis repository is used in the `npx create-turbo@latest` command and selected when choosing which package manager you wish to use with your monorepo (npm).\n\n### Build 🛠\n\nTo build all apps and packages, run the following command:\n\n```sh\nnpm run build\n```\n\n### Develop 💻\n\nTo develop all apps and packages, run the following command:\n\n```sh\nnpm run dev\n```\n\n### Remote Caching 💽\n\nTurborepo can use a technique known as [Remote Caching (Beta)](https://turborepo.org/docs/core-concepts/remote-caching) to share cache artefacts across machines, enabling you to share build caches with your team and CI/CD pipelines.\n\nBy default, Turborepo will cache locally. To enable Remote Caching (Beta), you will need an account with Vercel. If you don't have an account, you can [create one](https://vercel.com/signup), then enter the following commands:\n\n```sh\nnpx turbo login\n```\n\nThis will authenticate the Turborepo CLI with your [Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).\n\nNext, you can link your Turborepo to your Remote Cache by running the following command from the root of your turborepo:\n\n```sh\nnpx turbo link\n```\n\n## Useful Links 🔗\n\n### Remix + Cloudflare\n\n- [Remix](https://remix.run/docs/en/v1)\n- [Cloudflare](https://www.cloudflare.com)\n- [Workers](https://developers.cloudflare.com/workers/)\n- [KV](https://developers.cloudflare.com/workers/runtime-apis/kv/)\n- [Durable Objects](https://developers.cloudflare.com/workers/runtime-apis/durable-objects/)\n- [Usage and Practical applications of DO](https://developers.cloudflare.com/workers/learning/using-durable-objects/)\n- [Wrangler](https://developers.cloudflare.com/workers/wrangler/)\n- [Wrangler Configuration file reference](https://developers.cloudflare.com/workers/wrangler/configuration/)\n- [Wrangler KV](https://developers.cloudflare.com/workers/wrangler/workers-kv/)\n\n### Turborepo\n\nLearn more about the power of Turborepo:\n\n- [Pipelines](https://turborepo.org/docs/core-concepts/pipelines)\n- [Caching](https://turborepo.org/docs/core-concepts/caching)\n- [Remote Caching (Beta)](https://turborepo.org/docs/core-concepts/remote-caching)\n- [Scoped Tasks](https://turborepo.org/docs/core-concepts/scopes)\n- [Configuration Options](https://turborepo.org/docs/reference/configuration)\n- [CLI Usage](https://turborepo.org/docs/reference/command-line-reference)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGirish21%2Fremix-cloudflare-workers-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGirish21%2Fremix-cloudflare-workers-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGirish21%2Fremix-cloudflare-workers-template/lists"}