Docs / Set up

Set up on Cloudflare Pages

EditStatic runs as Pages Functions middleware on your preview deployments, and only on the one address you choose. Production gets the same file but no settings, so it does nothing there.

1. Add the files

On your staging branch:

npx github:jefvandegraaf/edit-static init --host cloudflare --branch staging
git add functions/_middleware.js .github/workflows/editstatic.yml editstatic.config.json
git commit -m "Add EditStatic"
git push

If you already have a functions/_middleware.js, init stops instead of overwriting it. Cloudflare allows one middleware per folder, so rename yours and call it from a small wrapper.

Some server-rendered frameworks build their own _worker.js, and then Pages ignores the functions folder. Use Netlify for those sites.

2. Add the settings

Open Workers & Pages, your project, Settings, Variables and Secrets. Choose the Preview environment, not Production. Preview settings apply to every preview branch, which is why EDIT_HOST matters: it limits the editor to your staging alias.

Name	Value
`EDIT_PASSWORD`	A long password you choose. Keep it secret.
`GITHUB_TOKEN`	The token from GitHub: this one repo, Contents read and write. Keep it secret.
`GITHUB_REPO`	Your repo as `owner/name`, for example `you/your-site`
`GITHUB_BRANCH`	`staging`, or whichever branch the editing deployment builds from
`EDIT_HOST`	The staging address without `https://`, for example `staging.your-project.pages.dev`

The alias is the branch name in lowercase, with other characters turned into dashes: staging becomes staging.<project>.pages.dev.

3. Let the Action push

In the repo on GitHub: Settings, Actions, General, Workflow permissions, Read and write permissions, Save.

4. Redeploy and open

In Deployments, retry the latest staging deployment, because settings apply to new deployments. Then check /__es/api/health on the staging address and open it with ?edit.

Good to know

A save first commits a small file to .editstatic/pending/. Its commit message starts with [CF-Pages-Skip], so it doesn't start a build. The Action's commit with your edit does.
Single-page apps work without extra rules: Pages serves index.html for unknown paths when there's no 404.html.
To update EditStatic, run init again and commit the changed file.