Skip to content

Commit 5be70f8

Browse files
github-actions[bot]github-actions[bot]
committed
v2064: Create apps with native Worker Previews (samebase/samebase#1648)
Samebase-Source-Repository: samebase/samebase Samebase-Source-Commit: 20c6c5d0f81d38e113e3643b2a87b4dbd4bbe1ae Samebase-Source-Path: templates/base
1 parent 52d6288 commit 5be70f8

11 files changed

Lines changed: 311 additions & 553 deletions

‎README.md‎

Lines changed: 17 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -48,38 +48,28 @@ The core workflow runs on macOS, Linux, and Windows. See
4848

4949
## Checks and builds
5050

51-
| Command | Purpose |
52-
| --------------------------------- | -------------------------------------------------------------- |
53-
| `pnpm run check` | Format, lint, type-check, test, and verify generated redirects |
54-
| `pnpm run build` | Run the complete Cloudflare build path |
55-
| `pnpm run deploy:dry-run` | Validate a production upload without publishing it |
56-
| `pnpm run deploy:preview:dry-run` | Validate a preview upload without publishing it |
57-
58-
The dry-run commands need `CLOUDFLARE_WORKER_NAME`.
59-
60-
On macOS or Linux:
61-
62-
```sh
63-
export CLOUDFLARE_WORKER_NAME=my-worker
64-
```
65-
66-
On Windows PowerShell:
67-
68-
```powershell
69-
$env:CLOUDFLARE_WORKER_NAME = "my-worker"
70-
```
51+
| Command | Purpose |
52+
| ------------------------------------------ | -------------------------------------------------------------- |
53+
| `pnpm run check` | Format, lint, type-check, test, and verify generated redirects |
54+
| `pnpm run build` | Run the complete Cloudflare build path |
55+
| `pnpm run deploy:dry-run --name my-worker` | Build and validate a production upload without publishing it |
7156

7257
## Deployment contract
7358

7459
Cloudflare Workers Builds runs `pnpm run build` for all branches. It then uses:
7560

76-
| Branch type | Deploy command | Convex key |
77-
| ----------------------- | ------------------------- | --------------------------- |
78-
| `main` | `pnpm run deploy` | `CONVEX_DEPLOY_KEY` |
79-
| Non-production branches | `pnpm run deploy:preview` | `PREVIEW_CONVEX_DEPLOY_KEY` |
61+
| Branch type | Deploy command | Builds settings | `CONVEX_DEPLOY_KEY` value |
62+
| -------------- | ------------------------- | --------------- | -------------------------- |
63+
| `main` | `pnpm run deploy` | Production | Production deploy key |
64+
| Other branches | `pnpm run deploy:preview` | Previews Base | Project Preview deploy key |
65+
66+
`build`, `deploy`, and `deploy:preview` are the package-script interface used by Samebase. Keep these
67+
names when changing their implementation. Cloudflare supplies the appropriate build secrets for each
68+
environment. Convex rejects a production key on a preview branch.
8069

81-
`scripts/build-cloudflare.ts` selects the Convex key from `WORKERS_CI_BRANCH` and fails closed when
82-
the branch identity is missing. `scripts/verify-current-branch-head.ts` prevents an older concurrent
70+
`scripts/build-cloudflare.ts` deploys Convex only inside Workers Builds and uses `WORKERS_CI_BRANCH`
71+
as the stable preview name. Local builds only build the frontend.
72+
`scripts/verify-current-branch-head.ts` prevents an older concurrent
8373
build from deploying backend code after a newer commit reaches the same branch. `convex deploy
8474
--cmd` supplies `VITE_CONVEX_URL` to the frontend build, so it is not a Cloudflare build variable.
8575

@@ -94,7 +84,7 @@ and deploy behavior. Use the
9484
- `vite.config.ts` defines the TanStack Start SPA and prerender behavior.
9585
- `wrangler.jsonc` defines Cloudflare static assets, SPA fallback, and preview URLs.
9686
- `scripts/build-cloudflare.ts` owns the Cloudflare build and Convex deployment selection.
97-
- `scripts/deploy-cloudflare.ts` owns production, preview, and dry-run uploads.
87+
- The `deploy` and `deploy:preview` package scripts run Wrangler directly.
9888
- `convex/` contains the backend, schema, authentication, and generated Convex bindings.
9989
- `src/` contains the React application and routes.
10090

‎docs/cloudflare-workers-builds.md‎

Lines changed: 23 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -6,37 +6,32 @@ This app deploys through Cloudflare Workers Builds. The Cloudflare dashboard run
66

77
## Build Variables
88

9-
Set these build secrets in the Cloudflare Workers Builds settings:
9+
Set `CONVEX_DEPLOY_KEY` separately in **Settings > Builds > Variables and secrets**:
1010

11-
- `CONVEX_DEPLOY_KEY`
12-
- `PREVIEW_CONVEX_DEPLOY_KEY`
11+
- Production: a Convex production deploy key.
12+
- Previews Base: the Convex project's Preview deploy key.
13+
14+
These are build secrets. Previews Base runtime variables and secrets are Worker bindings, so they
15+
are not the place for a Convex deploy key. Samebase puts `SAMEBASE_CONVEX_PROJECT`, its project
16+
identity marker, in production build variables only.
1317

1418
Do not add `VITE_CONVEX_URL`. Convex supplies the selected deployment URL to the frontend command
1519
that runs through `convex deploy --cmd`.
1620

17-
Cloudflare Workers Builds has separate production and preview build triggers
18-
under the hood, but the dashboard currently shows one build-variable table. To
19-
keep dashboard and API-created configurations equivalent, store both secrets on
20-
both triggers. This also keeps the production and preview keys visible in the
21-
dashboard. Keep this shared layout until Cloudflare exposes separate production
22-
and preview build-variable views.
23-
24-
This template handles that dashboard limitation in `scripts/build-cloudflare.ts`:
25-
26-
1. It reads `WORKERS_CI_BRANCH`.
27-
2. It selects `CONVEX_DEPLOY_KEY` when the branch is `main`.
28-
3. It selects `PREVIEW_CONVEX_DEPLOY_KEY` for every other branch.
29-
4. It passes only the selected value to the Convex deploy subprocess as
30-
`CONVEX_DEPLOY_KEY`.
21+
Cloudflare supplies each environment's `CONVEX_DEPLOY_KEY` to the build. The build script does not
22+
select between two key names. Convex checks the key's deployment type before deploying.
3123

32-
That keeps the production key compatible with projects that do not use the
33-
preview-aware wrapper, while still requiring a separate preview key for
34-
non-production branches.
24+
Keep `pnpm run build`, `pnpm run deploy`, and `pnpm run deploy:preview` as the Builds commands.
25+
The deploy scripts run `wrangler deploy` and `wrangler preview`. Wrangler gets the Worker name from
26+
Workers Builds, so the template does not need a fixed name. `previews: {}` in `wrangler.jsonc`
27+
permits native preview deployment; it does not enable preview builds in the dashboard.
3528

36-
When configuring through the Builds API, write the same two secrets to both
37-
triggers. When configuring through the dashboard, enter both secrets in its
38-
build-variable table. The script selects the correct key for each branch and
39-
keeps preview builds from falling back to the production key.
29+
When migrating an existing app, open **Settings > Builds > Set up Worker Previews > Set up**,
30+
then select **Switch to Worker Previews**. Enable preview builds and replace the copied production
31+
key in Previews Base with the project's Preview key. Remove `PREVIEW_CONVEX_DEPLOY_KEY` from build settings.
32+
Existing branch previews keep their saved build variables. Use a new branch name after correcting
33+
Previews Base. Retrying or deleting the Worker preview does not reset those variables. Check both
34+
production and a new branch preview before finishing.
4035

4136
## Build Ordering
4237

@@ -61,15 +56,14 @@ concurrency primitive.
6156

6257
## Local Checks
6358

64-
Local dry-runs can validate the Worker package without build secrets:
59+
Local builds do not deploy Convex, even when a deploy key exists in the shell. A local dry run
60+
builds and validates the Worker package without publishing it:
6561

6662
```sh
67-
CLOUDFLARE_WORKER_NAME=my-worker vp run deploy:dry-run
68-
CLOUDFLARE_WORKER_NAME=my-worker vp run deploy:preview:dry-run
63+
pnpm run deploy:dry-run --name my-worker
6964
```
7065

71-
If you set either deploy key locally, also set `WORKERS_CI_BRANCH` so the
72-
script can choose the intended deployment target.
66+
Wrangler does not support a native preview dry run. Use a real test branch to verify a preview.
7367

7468
## References
7569

‎package.json‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,11 @@
1515
"dev:frontend": "vp dev",
1616
"dev:worktree": "node ./scripts/run-worktree-dev.ts",
1717
"check": "vp check && vp run typecheck && vp test && vp run verify:cloudflare-redirects && vp run verify:dev-launcher-version",
18-
"build": "vp run build:cloudflare",
18+
"build": "node ./scripts/build-cloudflare.ts",
1919
"build:app": "vp run check && vp build",
20-
"build:cloudflare": "node ./scripts/build-cloudflare.ts",
21-
"deploy": "node ./scripts/deploy-cloudflare.ts deploy",
22-
"deploy:preview": "node ./scripts/deploy-cloudflare.ts preview",
23-
"deploy:dry-run": "node ./scripts/deploy-cloudflare.ts deploy --dry-run",
24-
"deploy:preview:dry-run": "node ./scripts/deploy-cloudflare.ts preview --dry-run",
20+
"deploy": "wrangler deploy",
21+
"deploy:preview": "wrangler preview",
22+
"deploy:dry-run": "pnpm run build && wrangler deploy --dry-run",
2523
"format": "vp fmt",
2624
"format:check": "vp fmt --check",
2725
"generate:cloudflare-redirects": "node ./scripts/generate-cloudflare-redirects.ts",
@@ -64,7 +62,7 @@
6462
"vite": "catalog:",
6563
"vite-plus": "catalog:",
6664
"vitest": "catalog:",
67-
"wrangler": "^4.118.0"
65+
"wrangler": "4.136.2"
6866
},
6967
"packageManager": "pnpm@11.1.1"
7068
}

0 commit comments

Comments
 (0)