From a045c571642770ad8038ccf5ca9d09e08270fc05 Mon Sep 17 00:00:00 2001 From: Girish21 Date: Sat, 11 Jun 2022 23:50:30 +0530 Subject: [PATCH] update readme --- README.md | 151 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 122 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 104a96b..ef8ae1b 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,140 @@ -# Remix + Cloudflare Workers starter with Turborepo +# Remix + Cloudflare Workers starter with Turborepo 🚀 -Starter to get going with Remix and Cloudflare Workers +Starter to get going with Remix and Cloudflare Workers. -## What's inside? +This 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/)). + +## What's inside? 👀 This turborepo uses [npm](https://www.npmjs.com/) as a package manager. It includes the following packages/apps: -### Apps and Packages +### Apps and Packages 📦 -- `docs`: a [Next.js](https://nextjs.org) app -- `web`: another [Next.js](https://nextjs.org) app -- `ui`: a stub React component library shared by both `web` and `docs` applications -- `eslint-config-custom`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`) +- `counter-do`: a [Durable Object](https://developers.cloudflare.com/workers/runtime-apis/durable-objects) class for managing the count state +- `remix-app`: a [Remix](https://remix.run) app +- `worker`: a [Worker](https://developers.cloudflare.com/workers) handler function +- `cloudflare-env`: types for Cloudflare environement variables +- `eslint-config-custom`: `eslint` configurations (includes `@remix-run/eslint-config` and `eslint-config-prettier`) - `tsconfig`: `tsconfig.json`s used throughout the monorepo -Each package/app is 100% [TypeScript](https://www.typescriptlang.org/). +## Getting Started 🪄 + +Durable Objects are only available with a Workers paid subscription. However, you can upgrade to the paid plan from the [Dashboard](https://dash.cloudflare.com). -### Utilities +Let's setup `wrangler` CLI [instalation](https://github.com/cloudflare/wrangler#installation) (wrangler requires a minimum Node version of `16`) -This turborepo has some additional tools already setup for you: +```sh +npm i @cloudflare/wrangler -g +``` -- [TypeScript](https://www.typescriptlang.org/) for static type checking -- [ESLint](https://eslint.org/) for code linting -- [Prettier](https://prettier.io) for code formatting +After installation, log in to our Cloudflare account from the CLI. -## Setup +```sh +wrangler login +``` -This 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). +Next, we have to add Cloudflare Account ID in the [`wrangler.toml`](./packages/worker/wrangler.toml). You can get the Account ID by visiting the [`Workers` Dashboard](https://dash.cloudflare.com). -### Build +```toml +account_id = "xxx" +``` -To build all apps and packages, run the following command: +Also, remember to change the worker's name while we're here. + +```toml +name = "remix-worker" # can be any name +``` + +That's all we're ready to push to prod! 🚀 + +Before 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. + +```sh +git add -A -m "" +git push +``` + +### Recap 🌀 +```sh +npm i @cloudflare/wrangler -g +wrangler login +# update wrangler.toml with the Account ID +# update Worker name +# configure CF_API_TOKEN action secret +git add -A -m "" +git push ``` -cd my-turborepo + +## Durable Objects 🔥 + +This starter template comes with a simple DO implementation to keep track of the number of times the root loader is invoked. + +If you're starting with DO and not sure what it is, go through the official docs on [Durable Objects](https://remix.run/docs/en/v1/api/conventions#page-context-in-meta-function) will be a good start! + +## Worker KV 📒 + +KV [docs](https://developers.cloudflare.com/workers/runtime-apis/kv/). +Wrangler KV CLI [docs](https://developers.cloudflare.com/workers/wrangler/workers-kv/) + +This template does not come with a KV namespace attached to it. However, you can create one using the Wrangler CLI. + +```sh +wrangler kv:namespace create "MY_KV" +``` + +The 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 + +```toml +kv_namespaces = [ + { binding = "MY_KV", id = "xxxx" } +] +``` + +We must add this above the `[site]` block in the `toml` file. We have added the KV namespace binding for the production environment, but we also need a namespace for `dev`. We can do that by running. + +```sh +wrangler kv:namespace create "MY_KV" --preview +``` + +This will generate a namespace for the `dev` environment, and we must add this below the `[env.dev]` block in the configuration file. + +```toml +[env.dev] +kv_namespaces = [ + { binding = "MY_KV", id = "xxxx", preview_id = "xxxx" } +] +``` + +**Note**: We need to add the `preview_id` key to the configuration file along with the `id` key with the same value. + +## Turbo Setup ✨ + +This 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). + +### Build 🛠 + +To build all apps and packages, run the following command: + +```sh npm run build ``` -### Develop +### Develop 💻 To develop all apps and packages, run the following command: -``` -cd my-turborepo +```sh npm run dev ``` -### Remote Caching +### Remote Caching 💽 -Turborepo can use a technique known as [Remote Caching (Beta)](https://turborepo.org/docs/core-concepts/remote-caching) to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines. +Turborepo 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. -By 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: +By 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: -``` -cd my-turborepo +```sh npx turbo login ``` @@ -61,11 +142,23 @@ This will authenticate the Turborepo CLI with your [Vercel account](https://verc Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your turborepo: -``` +```sh npx turbo link ``` -## Useful Links +## Useful Links 🔗 + +### Remix + Cloudflare + +- [Remix](https://remix.run/docs/en/v1) +- [Cloudflare](https://www.cloudflare.com) +- [Workers](https://developers.cloudflare.com/workers/) +- [KV](https://developers.cloudflare.com/workers/runtime-apis/kv/) +- [Durable Objects](https://developers.cloudflare.com/workers/runtime-apis/durable-objects/) +- [Wrangler](https://developers.cloudflare.com/workers/wrangler/) +- [Wrangler KV](https://developers.cloudflare.com/workers/wrangler/workers-kv/) + +### Turborepo Learn more about the power of Turborepo: