Riebeckite
Menu
Color mode

Cloudflare Workers deployment

This guide focuses only on publishing a Riebeckite site to Cloudflare Workers.

Prerequisites

In the site folder, make sure these commands succeed.

sh
npm install
npm exec riebeckite build

A successful build creates dist/. Cloudflare Workers will serve the files from that folder.

Incremental processing happens during riebeckite build on your machine or GitHub Actions runner. Wrangler then uploads the newly generated dist/ as Workers Static Assets; Workers do not perform incremental builds. The generated GitHub Actions workflow persists .riebeckite/cache and .riebeckite/build/content-state.json for this build step, never dist/.

1. Create a Cloudflare account

Create an account at cloudflare.com. The free plan is enough to get started.

2. Get wrangler

A site generated with create-riebeckite's Cloudflare Workers choice already includes the Wrangler dependency and wrangler.jsonc, so no extra install or setup is needed.

For a site generated with Not now, or when preparing one manually, run this in the site folder:

sh
npm install -D wrangler

wrangler is the official command-line tool for deploying to Cloudflare Workers.

3. Add wrangler.jsonc

npm exec riebeckite deploy creates wrangler.jsonc from the site folder name when the file is missing, so this step is only needed when you want to review or customize it. To create it yourself, add a wrangler.jsonc in the site root:

text
my-site/
|- dist/
|- package.json
|- riebeckite.config.ts
`- wrangler.jsonc

Change name first.

jsonc
{
  "name": "my-riebeckite-site",
  "assets": {
    "directory": "./dist"
  }
}

name is the Worker name on Cloudflare. Choose a name that is unique to you. Keep assets.directory as ./dist.

4. Log in to Cloudflare

riebeckite deploy opens the browser and asks you to log in on the first run. To log in ahead of time, or if you run Wrangler directly, use:

sh
npx wrangler login

A browser window opens. Log in to Cloudflare and grant access.

5. Deploy

sh
npm exec riebeckite deploy

riebeckite deploy calls Wrangler to publish dist/. It logs you in first when needed and creates wrangler.jsonc when it is missing. Choosing Cloudflare Workers in create-riebeckite and answering Yes to Deploy now? runs this build and deploy immediately after scaffolding. To run Wrangler directly instead, use npx wrangler deploy.

The deploy prints a URL such as https://<name>.<account>.workers.dev. Open it in a browser. If the site loads, deployment worked.

6. Match baseUrl to the deployed URL

After the first successful deploy, update baseUrl in riebeckite.config.ts.

ts
site: {
  baseUrl: "https://my-riebeckite-site.example.workers.dev",
},

Then build and deploy again.

sh
npm exec riebeckite build
npm exec riebeckite deploy

This makes sitemap and feed URLs match the public site.

Check without publishing

Use these commands if you want to verify before uploading.

sh
npm exec -- riebeckite deploy --dry-run
npx wrangler dev

--dry-run validates the configuration and files. wrangler dev serves a local version close to the deployed Worker.

Automated deployment with GitHub Actions

Instead of running npm exec riebeckite deploy manually, you can deploy when you push to GitHub.

If the site is already published from your machine, promote it from the site folder:

sh
npm exec riebeckite deploy setup

This creates .github/workflows/deploy.yml and registers CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID as repository secrets, then waits for you to push.

For a same-repository site that is not published yet, generate the workflow with:

sh
npx create-riebeckite my-site --github-actions

For a separate content repository, generate both workflow files with:

sh
npx create-riebeckite my-site --github-actions \
  --content-repository OWNER/notes \
  --site-repository OWNER/my-site

The external form checks out OWNER/notes into content/, receives content-updated repository dispatch events, and writes github/notify-site.yml for the content repository. Copy that file to .github/workflows/notify-site.yml in the content repository. An external checkout alone does not start the site workflow on a content push.

See GitHub Actions for the full workflow.

Next steps

History

1 changesCollapseExpand
1 + # Cloudflare Workers deployment
2 +
3 + This guide focuses only on publishing a Riebeckite site to Cloudflare Workers.
4 +
5 + ## Prerequisites
6 +
7 + In the site folder, make sure these commands succeed.
8 +
9 + ```sh
10 + npm install
11 + npm exec riebeckite build
12 + ```
13 +
14 + A successful build creates `dist/`. Cloudflare Workers will serve the files from that folder.
15 +
16 + Incremental processing happens during `riebeckite build` on your machine or GitHub Actions runner. Wrangler then uploads the newly generated `dist/` as Workers Static Assets; Workers do not perform incremental builds. The generated GitHub Actions workflow persists `.riebeckite/cache` and `.riebeckite/build/content-state.json` for this build step, never `dist/`.
17 +
18 + ## 1. Create a Cloudflare account
19 +
20 + Create an account at [cloudflare.com](https://www.cloudflare.com/). The free plan is enough to get started.
21 +
22 + ## 2. Get wrangler
23 +
24 + A site generated with `create-riebeckite`'s `Cloudflare Workers` choice already includes the Wrangler dependency and `wrangler.jsonc`, so no extra install or setup is needed.
25 +
26 + For a site generated with `Not now`, or when preparing one manually, run this in the site folder:
27 +
28 + ```sh
29 + npm install -D wrangler
30 + ```
31 +
32 + wrangler is the official command-line tool for deploying to Cloudflare Workers.
33 +
34 + ## 3. Add wrangler.jsonc
35 +
36 + `npm exec riebeckite deploy` creates `wrangler.jsonc` from the site folder name when the file is missing, so this step is only needed when you want to review or customize it. To create it yourself, add a `wrangler.jsonc` in the site root:
37 +
38 + ```text
39 + my-site/
40 + |- dist/
41 + |- package.json
42 + |- riebeckite.config.ts
43 + `- wrangler.jsonc
44 + ```
45 +
46 + Change `name` first.
47 +
48 + ```jsonc
49 + {
50 + "name": "my-riebeckite-site",
51 + "assets": {
52 + "directory": "./dist"
53 + }
54 + }
55 + ```
56 +
57 + `name` is the Worker name on Cloudflare. Choose a name that is unique to you. Keep `assets.directory` as `./dist`.
58 +
59 + ## 4. Log in to Cloudflare
60 +
61 + `riebeckite deploy` opens the browser and asks you to log in on the first run. To log in ahead of time, or if you run Wrangler directly, use:
62 +
63 + ```sh
64 + npx wrangler login
65 + ```
66 +
67 + A browser window opens. Log in to Cloudflare and grant access.
68 +
69 + ## 5. Deploy
70 +
71 + ```sh
72 + npm exec riebeckite deploy
73 + ```
74 +
75 + `riebeckite deploy` calls Wrangler to publish `dist/`. It logs you in first when needed and creates `wrangler.jsonc` when it is missing. Choosing `Cloudflare Workers` in `create-riebeckite` and answering `Yes` to `Deploy now?` runs this build and deploy immediately after scaffolding. To run Wrangler directly instead, use `npx wrangler deploy`.
76 +
77 + The deploy prints a URL such as `https://<name>.<account>.workers.dev`. Open it in a browser. If the site loads, deployment worked.
78 +
79 + ## 6. Match baseUrl to the deployed URL
80 +
81 + After the first successful deploy, update `baseUrl` in `riebeckite.config.ts`.
82 +
83 + ```ts
84 + site: {
85 + baseUrl: "https://my-riebeckite-site.example.workers.dev",
86 + },
87 + ```
88 +
89 + Then build and deploy again.
90 +
91 + ```sh
92 + npm exec riebeckite build
93 + npm exec riebeckite deploy
94 + ```
95 +
96 + This makes sitemap and feed URLs match the public site.
97 +
98 + ## Check without publishing
99 +
100 + Use these commands if you want to verify before uploading.
101 +
102 + ```sh
103 + npm exec -- riebeckite deploy --dry-run
104 + npx wrangler dev
105 + ```
106 +
107 + `--dry-run` validates the configuration and files. `wrangler dev` serves a local version close to the deployed Worker.
108 +
109 + ## Automated deployment with GitHub Actions
110 +
111 + Instead of running `npm exec riebeckite deploy` manually, you can deploy when you push to GitHub.
112 +
113 + If the site is already published from your machine, promote it from the site folder:
114 +
115 + ```sh
116 + npm exec riebeckite deploy setup
117 + ```
118 +
119 + This creates `.github/workflows/deploy.yml` and registers `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` as repository secrets, then waits for you to push.
120 +
121 + For a same-repository site that is not published yet, generate the workflow with:
122 +
123 + ```sh
124 + npx create-riebeckite my-site --github-actions
125 + ```
126 +
127 + For a separate content repository, generate both workflow files with:
128 +
129 + ```sh
130 + npx create-riebeckite my-site --github-actions \
131 + --content-repository OWNER/notes \
132 + --site-repository OWNER/my-site
133 + ```
134 +
135 + The external form checks out `OWNER/notes` into `content/`, receives
136 + `content-updated` repository dispatch events, and writes `github/notify-site.yml`
137 + for the content repository. Copy that file to
138 + `.github/workflows/notify-site.yml` in the content repository. An external
139 + checkout alone does not start the site workflow on a content push.
140 +
141 + See [GitHub Actions](./github-actions.en.md) for the full workflow.
142 +
143 + ## Next steps
144 +
145 + - [Fast path to publishing a site](../../getting-started/deployment.en.md)
146 + - [Usage Guide](../README.en.md)
147 + - [CLI](../../reference/cli.en.md)
148 +