From c87c99254b50d58b5fd764a70dcf42e1b6a44265 Mon Sep 17 00:00:00 2001
From: Edmund Hung <me@edmund.dev>
Date: Sun, 11 Feb 2024 23:10:20 +0100
Subject: [PATCH] docs: update readme

---
 .github/workflows/ci.yml               |   4 +-
 .gitignore                             |   1 +
 README.md                              | 101 +++++++++++++++++++++----
 wrangler.toml => wrangler.toml.example |   6 +-
 4 files changed, 95 insertions(+), 17 deletions(-)
 rename wrangler.toml => wrangler.toml.example (59%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a2ae3b6..4cd5de9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -18,8 +18,8 @@ jobs:
           useLockFile: false
       - name: 🎭 Install Playwright
         run: npx playwright install --with-deps
-      - name: 📦 Build the worker
-        run: npx remix vite:build
+      - name: 📦 Prepare the environment
+        run: cp wrangler.toml.example wrangler.toml
       - name: 💣 Run some tests
         run: npx playwright test
 
diff --git a/.gitignore b/.gitignore
index c2a97d3..2565be0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@ node_modules
 
 # Cloudflare
 .wrangler
+wrangler.toml
 
 # Playwright
 /test-results
diff --git a/README.md b/README.md
index 9f23b11..afd4cef 100644
--- a/README.md
+++ b/README.md
@@ -3,40 +3,113 @@
 Learn more about [Remix Stacks](https://remix.run/stacks).
 
 ```
-npx create-remix --template edmundhung/remix-cloudflare-template
+npx create-remix@latest --template edmundhung/remix-cloudflare-template
 ```
 
 What's included?
 
-- Deploying to [Cloudflare Page](https://workers.cloudflare.com/)
-- CI on [Github Actions](https://github.com/features/actions)
+- Development with [Vite](https://vitejs.dev)
+- [Github Actions](https://github.com/features/actions) for CI/CD
+- [Markdoc](https://markdoc.dev) for rendering markdown
 - Styling with [Tailwind](https://tailwindcss.com/)
-- Testing using [Playwright](playwright.dev/) with _undici_ mocking support
+- End-to-end testing with [Playwright](playwright.dev/)
+- Local third party request mocking with [MSW](https://mswjs.io/)
 - Code formatting with [Prettier](https://prettier.io)
 - Linting with [ESLint](https://eslint.org)
 - Static Types with [TypeScript](https://typescriptlang.org)
 
-## Node Version
+## Development
 
-Please make sure the node version is **>= 18**.
+Before start, copy `wrangler.toml.example` and name it `wrangler.toml`. This
+file will be used to configure the development environment and define all the
+environment variables that you need for your application.
 
-## Development
+```sh
+cp wrangler.toml.example wrangler.toml
+```
 
-To starts your app with the vite dev server, run the following command:
+To starts the vite dev server:
 
 ```sh
 npm run dev
 ```
 
-## Testing
+You can also start the Playwright UI mode to test your application. You will
+find all the tests defined in the [/tests/e2e](./tests/e2e/) directory.
+
+```sh
+npm run test
+```
 
-Before running the tests, please ensure the app is built:
+To test your application on the workerd runtime, you can start the wrangler dev
+server with:
 
 ```sh
-npm run build && npm run test
+npm run build && npm run start
+```
+
+### New environment variable
+
+To add a new environment variable, you can update the **var** section on the
+[wrangler.toml](./wrangler.toml) file with the new variable:
+
+```toml
+[vars]
+NEW_VARIABLE = "..."
+```
+
+The variable will be available from the `env` object in the context.
+
+### Setup a KV Namespace
+
+To setup a new KV namespace on the **development environment**, update
+[wrangler.toml](./wrangler.toml) with another object similar to the cache
+namespace as shown below:
+
+```toml
+kv_namespaces = [
+  { binding = "cache", id = "cache" },
+  { binding = "new_namespace", id = "new_namespace" }
+]
 ```
 
-## CI/CD
+Note that the `id` has no effect on the dev environment. You can use the same
+name for both `id` and `binding`. The namespace will be available form the `env`
+object in the context.
+
+### Improving types
+
+You can improve the types of the `env` object by updating
+[env.d.ts](./env.d.ts).
+
+## Deployment
+
+Before your first deployment, make sure all the environment variables and
+bindings are set properly on the
+[Cloudlfare Dashboard](https://dash.cloudflare.com/login).
+
+### Creating a new application
+
+To create a new application on the Cloudflare Dashboard, select **Workers and
+Pages** from the menu and click on **Create Application**. You can then follow
+the instructions based on your needs.
+
+### Setting up environment variables
+
+To set up environment variables, select **Workers and Pages** from the menu and
+look for the application details. You will find the **environment variables**
+section under the **Settings** tab.
+
+### Setting up KV namespaces
+
+To set up a new KV namespaces, you need to create a new namespace first through
+the **KV** menu under **Workers and Pages** and click **Create a namespace**.
+
+After creating the namespace, you can bind the namespace to the application from
+the application details page. You can find the setting from the **Functions**
+section under the **Settings** tab.
+
+### Debugging
 
-The template ships a [CI workflow](./.github/workflows/ci.yml) which is
-triggered whenever new changes are pushed.
+If your application is not working properly, you can find the real-time logs in
+the **Functions** tab from the deployment details page.
diff --git a/wrangler.toml b/wrangler.toml.example
similarity index 59%
rename from wrangler.toml
rename to wrangler.toml.example
index 01f7671..765717c 100644
--- a/wrangler.toml
+++ b/wrangler.toml.example
@@ -1,4 +1,8 @@
 name = "remix-cloudflare-template"
+compatibility_date = "2024-02-11"
 kv_namespaces = [
   { binding = "cache", id = "cache" }
-]
\ No newline at end of file
+]
+
+[vars]
+GITHUB_TOKEN = ""