Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions docs/integrations/cloudflare.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,6 +145,77 @@ Set these CI secrets and variables as needed:

For email, run `void email setup --platform cloudflare` locally, commit `void.lock.json`, and pass `--require-email` in CI. The token also needs Email Routing Edit and Email Sending Edit.

### Pull request previews

Give each pull request its own URL with [Cloudflare Previews](https://developers.cloudflare.com/workers/previews/). A Preview belongs to the same Worker but never receives production traffic. Previews are available for static sites, SPAs and supported SSGs.

```sh
void deploy --platform cloudflare --preview pr-64 --json # create or update
void preview delete pr-64 # remove
```

The CI job needs only `CLOUDFLARE_API_TOKEN` (Workers Scripts: Edit) and, when the token can access several accounts, `CLOUDFLARE_ACCOUNT_ID`. This workflow deploys a preview on every push to a pull request, comments its URL, and deletes it when the pull request closes:

```yaml
name: Preview

on:
pull_request:
types: [opened, synchronize, reopened, closed]

permissions:
contents: read
pull-requests: write

concurrency:
group: preview-${{ github.event.pull_request.number }}

jobs:
preview:
# Repository secrets are not available to pull requests from forks.
if: github.event.action != 'closed' && github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: lts/*
check-latest: true
cache: pnpm
- run: pnpm install --frozen-lockfile
- id: preview
run: |
set -o pipefail
url="$(pnpm exec void deploy --platform cloudflare --preview "pr-${{ github.event.pull_request.number }}" --json | jq -er '.previewUrl')"
echo "url=$url" >> "$GITHUB_OUTPUT"
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
- run: gh pr comment "${{ github.event.pull_request.number }}" --edit-last --create-if-none --body "Preview: ${{ steps.preview.outputs.url }}"
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

cleanup:
if: github.event.action == 'closed' && github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
with:
node-version: lts/*
check-latest: true
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm exec void preview delete "pr-${{ github.event.pull_request.number }}"
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
```

If the build runs in an earlier job, download its output and add `--skip-build`. Preview URLs are public; protect them with [Cloudflare Access](https://developers.cloudflare.com/workers/configuration/cloudflare-access/) when needed. See [`void deploy --preview`](../reference/cli/deploy.md#void-deploy-preview) for the JSON output and naming rules.

#### Cloudflare Access

For local deployment to an Access-protected Worker, you can use a short-lived user session:
Expand Down
4 changes: 3 additions & 1 deletion docs/reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Use this page as a command reference. If you are setting up a project for the fi
| `init`, `prepare`, `info`, `migrate` | [Project setup](./cli/setup.md) |
| `connect`, `auth`, `account`, `cloudflare` | [Connections and authentication](./cli/auth.md) |
| `project` | [Projects, teams, logs, and rollback](./cli/project.md) |
| `deploy` | [Deployment](./cli/deploy.md) |
| `deploy`, `preview` | [Deployment](./cli/deploy.md) |
| `db` | [Database](./cli/database.md) |
| `gen` | [Code generation](./cli/generate.md) |
| `secret`, `env` | [Secrets and environment](./cli/secrets.md) |
Expand All @@ -40,6 +40,8 @@ Platform administrators can also choose AI Gateway logging [per project](./cli/p
| --------------------------------- | ----------------------------------------------------------------------------- |
| `void deploy` | Build and deploy to the configured platform |
| `void deploy --skip-migrations` | Deploy code without applying application or authentication SQL migrations |
| `void deploy --preview <name>` | Deploy a Cloudflare Preview with its own URL; production is unchanged |
| `void preview delete <name>` | Delete a Cloudflare Preview |
| `void prepare` | Generate `.void` artifacts without starting Vite |
| `void info [--json]` | Inspect persistent resource names before moving their code |
| `void gen model <name> [cols...]` | Scaffold a Drizzle table and API routes |
Expand Down
43 changes: 43 additions & 0 deletions docs/reference/cli/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ void deploy [--project <name>] [--dir <path>] [--spa] [--skip-build] [--skip-mig
void deploy [--platform <cloudflare|void>] [--require-email]
void deploy --platform cloudflare --atomic
void deploy --platform cloudflare --provision
void deploy --platform cloudflare --preview <name> [--json]
```

Auto-detects your project type and chooses the right pipeline. See [Supported App Types](../../guide/app-types.md) and [Deployment](../../guide/deployment.md) for details.
Expand Down Expand Up @@ -39,6 +40,8 @@ For Drizzle projects, deploy performs a read-only schema drift check. If a new m
| `--require-email` | Fail when email cannot be set up instead of deploying without it; requires `--platform cloudflare` |
| `--provision` | Run resource provisioning again even when every resource exists, for example to enable D1 read replication on an existing database; requires `--platform cloudflare` |
| `--atomic` | Publish an existing Durable Object Worker directly; readiness is checked after traffic changes |
| `--preview <name>` | Create or update a Cloudflare Preview instead of production; see [Previews](#void-deploy-preview) |
| `--json` | With `--preview`, print the result as one JSON record on stdout; progress goes to stderr |
| `--debug` | Mirror the structured deploy log to stderr (also written to `~/.void/logs/`) |

`--atomic` applies to one deployment. For an existing Durable Object Worker that consistently cannot stage, set `deploy: { cloudflare: { mode: 'atomic' } }` in `void.config.ts` so plain `void deploy` uses atomic publication. The default is `staged`.
Expand Down Expand Up @@ -115,3 +118,43 @@ Sandbox requires [Workers Paid](https://dash.cloudflare.com/?to=/:account/worker
For email, set `email.from` and run `void email setup --platform cloudflare` locally. Commit the lock file and pass `--require-email` in CI. See [Email setup](../../guide/email/domains.md#your-own-cloudflare-account).

For Access credentials, Hyperdrive permissions, readiness, and rollback, see [Cloudflare deployment](../../integrations/cloudflare.md#deploy-to-your-own-cloudflare-account).

## `void deploy --platform cloudflare --preview <name>` {#void-deploy-preview}

Deploy the build to a named [Cloudflare Preview](https://developers.cloudflare.com/workers/previews/) of the same Worker:

```sh
void deploy --platform cloudflare --skip-build --preview pr-64 --json
```

A Preview has its own stable URL, `https://<name>-<worker>.<subdomain>.workers.dev`, which always serves its latest deployment. Deploying the same name again updates that URL. Production traffic, the active deployment, routes and schedules are unchanged.

Previews are available for static sites, SPAs and supported SSGs. Apps that need a Worker, such as server routes, bindings, migrations or secrets, are refused before anything is built or uploaded. A Preview does not inherit production secrets.

The name uses lowercase letters, digits and hyphens. `<name>-<worker>` must fit in 63 characters. Use a name derived from the pull request, such as `pr-64`, rather than a branch name.

With `--json`, stdout carries one line:

```json
{
"workerName": "my-app",
"previewName": "pr-64",
"previewUrl": "https://pr-64-my-app.my-team.workers.dev",
"deploymentId": "…",
"deploymentUrl": "https://…-my-app.my-team.workers.dev"
}
```

`previewUrl` always serves the latest deployment of this Preview. `deploymentUrl` serves only this deployment.

The Worker must allow Preview URLs. Void's production deploy turns them on when workers.dev is on. If you set `cloudflare.preview_urls` to `false` in `void.config.ts`, a preview deploy fails and says how to turn it back on. Workers Free allows 100 Previews per Worker; Cloudflare removes the least recently deployed one beyond that.

See [Pull request previews](../../integrations/cloudflare.md#pull-request-previews) for a GitHub Actions workflow.

## `void preview delete <name>` {#void-preview-delete}

```sh
void preview delete pr-64
```

Delete a Preview and all its deployments. Production is unchanged. Deleting a Preview that does not exist succeeds, so a cleanup job can run more than once. It uses the same account and Worker as `void deploy --platform cloudflare`.
6 changes: 6 additions & 0 deletions packages/deploy-cloudflare/src/diagnostics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -82,3 +82,9 @@ export function cloudflareCommandDiagnostic(result: CloudflareCommandResult): st
.slice(0, MAX_DIAGNOSTIC_LENGTH);
return bounded.length < message.length ? `${bounded}\n[diagnostic truncated]` : bounded;
}

/** The uploader's diagnostic as an optional result field. */
export function commandDiagnosticFields(result: CloudflareCommandResult): { diagnostic?: string } {
const diagnostic = cloudflareCommandDiagnostic(result);
return diagnostic ? { diagnostic } : {};
}
8 changes: 8 additions & 0 deletions packages/deploy-cloudflare/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -53,12 +53,20 @@ export {
type CloudflareVersionMetadata,
type CloudflareWorkersDevSubdomainLookup,
} from './version.ts';
export {
deleteCloudflarePreview,
deployCloudflarePreview,
validateCloudflarePreviewName,
type CloudflarePreviewDeleteResult,
type CloudflarePreviewDeployResult,
} from './preview.ts';
export { createCloudflareMetadataRunner } from './metadata.ts';
export { cloudflareCommandDiagnostic } from './diagnostics.ts';
export { VOID_SECRET_DRAFT_MESSAGE, VOID_SECRET_DRAFT_SOURCE } from './secret-draft.ts';

export type {
CloudflareOperation,
CloudflarePreviewUploadResult,
CloudflareUploadResult,
CloudflareProviderError,
} from './operations.ts';
19 changes: 19 additions & 0 deletions packages/deploy-cloudflare/src/operations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,15 @@ export type CloudflareOperation =
*/
interactive?: boolean;
} & WorkerTarget)
| ({
/**
* Create or update a named Workers Preview from the prebuilt output. A Preview has its own
* URL and settings and never receives production traffic.
*/
type: 'previews.deploy';
previewName: string;
} & WorkerTarget)
| ({ type: 'previews.delete'; previewName: string } & WorkerTarget)
| ({ type: 'triggers.deploy'; assets?: boolean } & WorkerTarget)
| ({ type: 'triggers.clear-crons' | 'triggers.clear-domains' } & WorkerTarget)
| ({ type: 'tail'; search?: string; versionId?: string; status?: 'error' } & WorkerTarget);
Expand All @@ -66,6 +75,16 @@ export type CloudflareUploadResult = {
workersDevUrl?: string;
};

/** Structured `previews.deploy` data, decoded by the runner from the provider's response. */
export type CloudflarePreviewUploadResult = {
previewId: string;
previewName: string;
deploymentId: string;
/** Absent when the Worker has Preview URLs turned off. */
previewUrl?: string;
deploymentUrl?: string;
};

export type CloudflareProviderError = {
code?: number;
message: string;
Expand Down
Loading