Secure deploy to Cloudflare

Step 1: Open the token form in the right account

In the dashboard, switch to the project's account and open Manage Account → Account API Tokens → Create Token → Custom token. An account token belongs to the account and can never reach another one. A user token (My Profile → API Tokens) works too, but you have to limit it to one account yourself (step 3).

Step 2: Name the token and add only the permissions the project uses

Name: e.g. my-app deploy. Then click Add more for every row you need. Look at the bindings in your wrangler.jsonc: d1_databases means D1, r2_buckets means R2, kv_namespaces means KV.

Workers Scripts covers deploys, secrets, Durable Objects and logs. If a deploy later fails with an error about a missing permission (Queues, Containers, Images), add just that one.

Step 3: Limit the token to one account

Only in the user token form: under Account Resources keep Include and replace All accounts with the project's account. This is the most important field of the whole form. The account token form does not have it, because the token is bound to the account.

Step 4: Allow the token only from your IP address

Under Client IP Address Filtering keep Allow and enter your public address. A leaked token is then useless anywhere else. Find your addresses with:

# your public IPv4 address
curl -4 -s https://ifconfig.me; echo

# your public IPv6 address (no output = you have none, skip it)
curl -6 -s --max-time 5 https://ifconfig.me; echo

If you also have IPv6, add it with Add more (the address, or its /64 range). Otherwise Wrangler may connect over IPv6 and get a 403. You can edit the list later, e.g. when your provider changes your address.

Step 5: Set the expiry, create the token and copy it

TTL is optional; a year is a good default, then you roll the token. Click Continue to summary → Create Token and copy the value. Do not send it in chat or email. It goes straight into the project in the next chapter. Copy the Account ID too: on Account home click the dots next to the account name and choose Copy account ID. The Account ID is not a secret.

Step 1: Write the Account ID into wrangler.jsonc

Add "account_id" right below "name". From now on every deploy and wrangler command of this project targets this account only. If the project has more Wrangler configs (e.g. a separate static Worker), add it to each of them.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Locked to one account: a deploy or any wrangler command cannot land in another account.
  // The API token lives in .env.deploy (see package.json scripts "deploy" and "wr").
  "account_id": "<ACCOUNT_ID>",
  // ... the rest of your config stays as it is
}

Step 2: Put the token into .env.deploy

Create the file in the project root and paste the token. Next.js, OpenNext and Vite load only .env, .env.local, .env.<mode> and .env.<mode>.local, so this file never gets into a build.

# Only for deploys and the wrangler CLI. Next.js, OpenNext and Vite never read this file.
CLOUDFLARE_API_TOKEN="<API_TOKEN>"

# only you can read the file
chmod 600 .env.deploy

# must print a .gitignore rule; if it prints nothing, add one
git check-ignore -v .env.deploy || echo '.env*' >> .gitignore

# Docker only: keep all env files out of the image
echo '.env*' >> .dockerignore

Step 3: Remove Cloudflare variables from all other env files

Delete the lines CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID from .env, .env.local, .env.production and similar. The account is in wrangler.jsonc now, so there is no second source of truth. The first command below must print nothing.

# Which env files still contain Cloudflare variables? (prints names, never values)
grep -l 'CLOUDFLARE_' .env .env.* .dev.vars 2>/dev/null | grep -v '^.env.deploy$'

# Show the variable names in .env without their values
sed 's/=.*/=<redacted>/' .env

Step 4: Let the npm scripts load the token

Each script starts its own bash, loads .env.deploy into it and runs one command. The token does not stay in your terminal, and OpenNext does not write values from the shell into the build. Replace the matching scripts in package.json:

"scripts": {
  "dev":     "bash -c 'set -a; . ./.env.deploy; set +a; exec next dev'",
  "cfbuild": "bash -c 'set -a; . ./.env.deploy; set +a; exec opennextjs-cloudflare build'",
  "preview": "bash -c 'set -a; . ./.env.deploy; set +a; opennextjs-cloudflare build && exec opennextjs-cloudflare preview'",
  "deploy":  "bash -c 'set -a; . ./.env.deploy; set +a; opennextjs-cloudflare build && scripts/keep-old-chunks.sh merge && opennextjs-cloudflare deploy && scripts/keep-old-chunks.sh save'",
  "wr":      "bash -c 'set -a; . ./.env.deploy; set +a; exec wrangler \"$@\"' wr"
}

"scripts": {
  "dev":    "bash -c 'set -a; . ./.env.deploy; set +a; exec wrangler dev'",
  "deploy": "bash -c 'set -a; . ./.env.deploy; set +a; exec wrangler deploy'",
  "wr":     "bash -c 'set -a; . ./.env.deploy; set +a; exec wrangler \"$@\"' wr"
}

dev needs the token only when a binding has "remote": true (it then reads production data). The script scripts/keep-old-chunks.sh used by deploy is in chapter 06.

Step 5: Use npm run -s wr -- instead of npx wrangler

Everything after -- goes to Wrangler. Replace npx wrangler in your README, docs and scripts as well, so nobody runs a command without the token.

# instead of:  npx wrangler <command>
npm run -s wr -- whoami
npm run -s wr -- tail
npm run -s wr -- d1 execute <DB_NAME> --remote --command "SELECT 1"
npm run -s wr -- r2 object get <BUCKET>/<KEY> --remote

Why not Wrangler's own --env-file? It works only after the command name (wrangler whoami --env-file=…), in front of it Wrangler prints just the help. The wrapper is simpler and the same for every command.

Step 1: Wrangler sees the token and the right account

npm run -s wr -- whoami
# → "You are logged in with an Account API Token" (or "User API Token")
#   and the account you expect

If you see a different account or an error, check the token value in .env.deploy and that you run the command in the project root.

Step 2: Without the wrapper, Wrangler is not signed in

npx wrangler whoami
# → "You are not authenticated. Please run `wrangler login`."
#   That is correct: without the wrapper there is no token. Do NOT run wrangler login.

If it says you are logged in, either an old OAuth session is active (run npx wrangler logout) or the token is still in .env or in your shell (open a new terminal and go back to step 3 of chapter 04).

Step 3: The build output contains no token

Build locally (this deploys nothing) and search the output. Both checks print only names, never the token itself.

npm run cfbuild

# OpenNext: no Cloudflare variable in the Worker bundle (must print 0)
grep -c CLOUDFLARE_ .open-next/cloudflare/next-env.mjs

# Any project: no value from .env.deploy anywhere in the build output.
# Prints file names only, never the values. Empty output = OK.
while IFS='=' read -r k v; do v=${v//\"/}; [ -n "$v" ] && [ "${k#\#}" = "$k" ] && \
  grep -rlF -- "$v" .open-next .next dist build 2>/dev/null | sed "s|^|$k found in: |"; done < .env.deploy

Something found? A Cloudflare variable is still in one of the .env files the build reads. Remove it and build again.

Step 1: Add the script that keeps old chunks

Save it as scripts/keep-old-chunks.sh. merge copies archived chunks into the fresh build (it never overwrites a new file), save adds the deployed chunks to the archive. The archive lives outside the project, in ~/next-deployments-old-assets/<project folder>, so a clean checkout or rm -rf .open-next cannot delete it.

#!/usr/bin/env bash
# Keeps the JS/CSS chunks of earlier builds available after a deploy.
#   merge  before the deploy: copy archived chunks into the fresh build (new files are never overwritten)
#   save   after a successful deploy: add the deployed chunks to the archive
# Archive: $OLD_ASSETS_DIR, default ~/next-deployments-old-assets/<project folder name>
set -euo pipefail

BUILD=".open-next/assets/_next/static"
ARCHIVE="${OLD_ASSETS_DIR:-$HOME/next-deployments-old-assets/$(basename "$PWD")}/$BUILD"

# Copy files from $1 to $2 that do not exist in $2 yet; the count goes to COPIED.
# Paths keep the leading "./" (build folders may start with "-").
COPIED=0
copy_missing() {
  local src=$1 dst=$2 f
  COPIED=0
  while IFS= read -r -d '' f; do
    if [ ! -e "$dst/$f" ]; then
      mkdir -p -- "$(dirname -- "$dst/$f")"
      cp -p -- "$src/$f" "$dst/$f"
      COPIED=$((COPIED + 1))
    fi
  done < <(cd "$src" && find . -type f -print0)
}

# Delete Windows "Zone.Identifier" files (created when files are copied through Windows Explorer into WSL).
remove_zone_ids() {
  local dir n
  for dir in "$@"; do
    [ -d "$dir" ] || continue
    n=$(find "$dir" -type f -name '*:Zone.Identifier' -print -delete | wc -l)
    [ "$n" -gt 0 ] && echo "keep-old-chunks: deleted $n Zone.Identifier files in $dir"
  done
  return 0
}

[ -d "$BUILD" ] || { echo "keep-old-chunks: $BUILD not found, run the build first" >&2; exit 1; }
remove_zone_ids "$ARCHIVE" "$BUILD"

case "${1:-}" in
  merge)
    if [ -d "$ARCHIVE" ]; then
      copy_missing "$ARCHIVE" "$BUILD"
      echo "keep-old-chunks: added $COPIED old files from $ARCHIVE"
    else
      echo "keep-old-chunks: no archive yet ($ARCHIVE), it starts with this deploy"
    fi
    ;;
  save)
    mkdir -p "$ARCHIVE"
    copy_missing "$BUILD" "$ARCHIVE"
    echo "keep-old-chunks: archived $COPIED new files to $ARCHIVE"
    ;;
  *)
    echo "usage: $0 merge|save" >&2
    exit 2
    ;;
esac

chmod +x scripts/keep-old-chunks.sh

Another location? Set OLD_ASSETS_DIR. The script deletes Windows Zone.Identifier files from the archive and the build, they appear when you copy files through Windows Explorer into WSL.

Step 2: Deploy

The deploy script from chapter 04 already calls both steps. The archive is updated only after a successful deploy, so a failed deploy never puts files that never went live into it.

npm run deploy
# 1. build  2. add old chunks  3. deploy  4. archive the deployed chunks
# Step 4 runs only when the deploy succeeded.

The first deploy prints no archive yet, which is fine. From the second one on you see added N old files. The archive grows by a few hundred kilobytes per deploy. If it ever gets large, delete the oldest build folders in it (older than a few weeks nobody needs them).