Existing Next.js App → Cloudflare Workers: Command Reference

Updated: October 29, 2026
Target: An existing, compatible Next.js 16 application using Cloudflare's vinext migration path.
Shell: Commands work in VS Code Terminal / PowerShell unless noted. Run them in the project root (where package.json lives).
Important: vinext is still beta. Check compatibility before deploying a production app. Commands assume npm.

1. Required commands in order

Step	Command	Purpose / description	When
1	`cd path/to/my-nextjs-app`	Open the folder of your existing Next.js app. Replace with your actual path.	Once per terminal session
2	`node -v`	Check installed Node.js version. Use a Node version supported by your project and current Cloudflare tooling.	Before setup
3	`npm list next`	Check the installed Next.js version. The documented vinext migration flow targets Next.js 16.	Before setup
4	`npm install`	Install dependencies specified in `package.json` and the lockfile.	Initially / after dependency changes
5	`npm install -D wrangler@latest`	Install the Cloudflare Workers CLI locally.	Once
6	`npx wrangler login`	Sign in to Cloudflare in your browser.	Once / as needed
7	`npx wrangler whoami`	Verify the Cloudflare account is authenticated.	After login
8	`npx vinext check`	Check application compatibility with vinext. Fix reported problems before continuing.	Before migration
9	`npx vinext init`	Configure your existing app for vinext. When asked, choose Cloudflare Workers. This creates/updates Vite, Wrangler, and npm scripts.	Once
10	`npm run dev:vinext`	Run and test the vinext version locally (stop with `Ctrl+C`).	Before deployment / during development
11	`npm run build:vinext`	Build the production bundle for the Cloudflare target.	Before deployment
12	`npx @vinext/cloudflare deploy`	Deploy your configured Next.js app to Cloudflare Workers. Returns the deployment URL.	Each release

Note: Step 9 creates the deployment configuration. Review the resulting wrangler.jsonc / wrangler.toml, vite.config.ts, and package.json. Do not copy arbitrary configuration from another project. If npx vinext check finds incompatibilities, these steps are not guaranteed to work until fixed.

2. Environment variables and secrets (`.env` / `.dev.vars`)

Different places serve different purposes:

Local Worker runtime secrets: put them in .dev.vars OR .env at the project root. Do not use both for the same Worker environment: when .dev.vars exists, Cloudflare does not load .env values into Worker bindings.
Production secrets: configure them on the deployed Worker using wrangler secret put. Local files are not uploaded automatically.
Public build-time variables: variables beginning with NEXT_PUBLIC_ are intended to be visible to clients, and may be embedded at build time. Supply them to the build process as required by your actual vinext/Vite setup. They are not secrets. Verify the final client value after deploying.
Nonsecret Worker runtime variables: you may specify them in the Wrangler configuration's vars, rather than using secret put.
Existing Next.js .env.local: keep it if you still use next dev, but for the Cloudflare local runtime use the matching Worker local-env mechanism and test both separately.

Environment commands

Command	Purpose / description	Required?
`New-Item -ItemType File .dev.vars`	Create a local Worker secrets file in PowerShell (only if it doesn't already exist).	If using local secrets
`notepad .dev.vars`	Edit the local file on Windows and add real local values.	If using local secrets
`npx wrangler secret put DATABASE_URL`	Prompt for the production database URL and store it as an encrypted Worker secret.	If using a database URL
`npx wrangler secret put JWT_SECRET`	Prompt for the production authentication signing secret.	If using that secret
`npx wrangler secret put API_KEY`	Prompt for a production private API key. Replace `API_KEY` with your app's real variable name.	If applicable
`npx wrangler secret list`	List configured production secret names (not values).	Verification
`npx wrangler secret delete API_KEY`	Remove an obsolete secret from the deployed Worker.	Optional
`npx wrangler secret put JWT_SECRET --env staging`	Set a secret for a named staging environment, if one exists in your Wrangler config.	Optional

Sample .dev.vars content (placeholders only — replace before local testing):

DATABASE_URL="postgresql://user:password@host:5432/mydb"
JWT_SECRET="replace-with-a-long-random-secret"
API_KEY="replace-with-your-private-api-key"

For a public, nonsecret runtime value, edit the generated Wrangler config (illustrative JSONC — merge into your existing file, do not replace the entire file):

{
  "vars": {
    "PUBLIC_SITE_URL": "https://my-app.example.com"
  }
}

For a build-time public variable, an example for Windows PowerShell is:

$env:NEXT_PUBLIC_API_URL = "https://api.example.com"
npm run build:vinext
npx @vinext/cloudflare deploy

Check that your build tooling actually reads and embeds this value; NEXT_PUBLIC_ support varies with the adapter/transform and whether the value is accessed in client or server code. A runtime Worker secret will not automatically replace a value already baked into client JavaScript.

Prevent accidental Git commits

Add these entries to .gitignore (edit manually if already present):

.env*
.dev.vars*
!.env.example
!.dev.vars.example

Do not commit actual credentials. If you previously committed them, removing the file alone is insufficient: rotate the exposed credentials.

3. Build, release, diagnostics, and maintenance

Command	Description
`npm run dev:vinext`	Start the vinext development server.
`npm run build:vinext`	Test a production build.
`npx @vinext/cloudflare deploy`	Deploy the latest application to Workers.
`npx wrangler deployments list`	Show recent Worker deployments when supported by your configuration.
`npx wrangler tail`	Stream live Worker logs to investigate runtime errors.
`npx wrangler secret list`	Confirm production secret names exist.
`npx wrangler whoami`	Check Cloudflare authentication.
`npm list next`	Show the Next.js version.
`npx wrangler --version`	Show the Wrangler version.

4. Typical first deployment checklist

Ensure you are using a supported Next.js version and all dependencies install.
Run npx vinext check; resolve any unsupported APIs, native Node.js modules, or build errors.
Run npx vinext init; select Cloudflare Workers.
Create .dev.vars for local server secrets, if needed. Do not commit it.
Test with npm run dev:vinext, including login, database requests, and API routes.
Run npm run build:vinext and resolve production build errors.
Run npx @vinext/cloudflare deploy for the first deployment.
Add production secrets with npx wrangler secret put <NAME>; check with npx wrangler secret list. You can add them before first deploy if the target Worker already exists; otherwise deploy initially and add secrets, then verify/redeploy as needed.
For NEXT_PUBLIC_ values, ensure build-time values are correct and rebuild/redeploy after changing them.
Open the returned *.workers.dev URL and test actual production behavior, not just the homepage.

5. Common problems to check

Symptom	What to check
`Missing script: dev:vinext`	`vinext init` did not finish successfully or you're in the wrong directory; inspect `package.json`.
`Missing script: build:vinext`	Confirm initialization and the generated build script.
`Unauthorized` or account error	Run `npx wrangler login`, then `npx wrangler whoami`.
Environment variable is `undefined` on Cloudflare	Did you only set `.env.local` or `.dev.vars`? Add the production secret or Wrangler `vars` as appropriate.
Variable works server-side but not in the browser	Browser variables are public/build-time; verify `NEXT_PUBLIC_` and rebuild. Never send secrets to browser code.
Database doesn't connect	Verify driver and database are compatible with Workers, secrets are set, network/TLS rules allow access, and pooling is correct.
Build works but some routes fail	Check Cloudflare Worker logs using `npx wrangler tail` and review vinext compatibility.

Official documentation

Existing Next.js App → Cloudflare Workers: Command Reference

1. Required commands in order

Step	Command	Purpose / description	When
1	`cd path/to/my-nextjs-app`	Open the folder of your existing Next.js app. Replace with your actual path.	Once per terminal session
2	`node -v`	Check installed Node.js version. Use a Node version supported by your project and current Cloudflare tooling.	Before setup
3	`npm list next`	Check the installed Next.js version. The documented vinext migration flow targets Next.js 16.	Before setup
4	`npm install`	Install dependencies specified in `package.json` and the lockfile.	Initially / after dependency changes
5	`npm install -D wrangler@latest`	Install the Cloudflare Workers CLI locally.	Once
6	`npx wrangler login`	Sign in to Cloudflare in your browser.	Once / as needed
7	`npx wrangler whoami`	Verify the Cloudflare account is authenticated.	After login
8	`npx vinext check`	Check application compatibility with vinext. Fix reported problems before continuing.	Before migration
9	`npx vinext init`	Configure your existing app for vinext. When asked, choose Cloudflare Workers. This creates/updates Vite, Wrangler, and npm scripts.	Once
10	`npm run dev:vinext`	Run and test the vinext version locally (stop with `Ctrl+C`).	Before deployment / during development
11	`npm run build:vinext`	Build the production bundle for the Cloudflare target.	Before deployment
12	`npx @vinext/cloudflare deploy`	Deploy your configured Next.js app to Cloudflare Workers. Returns the deployment URL.	Each release

2. Environment variables and secrets (`.env` / `.dev.vars`)

Different places serve different purposes:

Local Worker runtime secrets: put them in .dev.vars OR .env at the project root. Do not use both for the same Worker environment: when .dev.vars exists, Cloudflare does not load .env values into Worker bindings.
Production secrets: configure them on the deployed Worker using wrangler secret put. Local files are not uploaded automatically.
Public build-time variables: variables beginning with NEXT_PUBLIC_ are intended to be visible to clients, and may be embedded at build time. Supply them to the build process as required by your actual vinext/Vite setup. They are not secrets. Verify the final client value after deploying.
Nonsecret Worker runtime variables: you may specify them in the Wrangler configuration's vars, rather than using secret put.
Existing Next.js .env.local: keep it if you still use next dev, but for the Cloudflare local runtime use the matching Worker local-env mechanism and test both separately.

Environment commands

Command	Purpose / description	Required?
`New-Item -ItemType File .dev.vars`	Create a local Worker secrets file in PowerShell (only if it doesn't already exist).	If using local secrets
`notepad .dev.vars`	Edit the local file on Windows and add real local values.	If using local secrets
`npx wrangler secret put DATABASE_URL`	Prompt for the production database URL and store it as an encrypted Worker secret.	If using a database URL
`npx wrangler secret put JWT_SECRET`	Prompt for the production authentication signing secret.	If using that secret
`npx wrangler secret put API_KEY`	Prompt for a production private API key. Replace `API_KEY` with your app's real variable name.	If applicable
`npx wrangler secret list`	List configured production secret names (not values).	Verification
`npx wrangler secret delete API_KEY`	Remove an obsolete secret from the deployed Worker.	Optional
`npx wrangler secret put JWT_SECRET --env staging`	Set a secret for a named staging environment, if one exists in your Wrangler config.	Optional

Sample .dev.vars content (placeholders only — replace before local testing):

DATABASE_URL="postgresql://user:password@host:5432/mydb"
JWT_SECRET="replace-with-a-long-random-secret"
API_KEY="replace-with-your-private-api-key"

For a public, nonsecret runtime value, edit the generated Wrangler config (illustrative JSONC — merge into your existing file, do not replace the entire file):

{
  "vars": {
    "PUBLIC_SITE_URL": "https://my-app.example.com"
  }
}

For a build-time public variable, an example for Windows PowerShell is:

$env:NEXT_PUBLIC_API_URL = "https://api.example.com"
npm run build:vinext
npx @vinext/cloudflare deploy

Prevent accidental Git commits

Add these entries to .gitignore (edit manually if already present):

.env*
.dev.vars*
!.env.example
!.dev.vars.example

Do not commit actual credentials. If you previously committed them, removing the file alone is insufficient: rotate the exposed credentials.

3. Build, release, diagnostics, and maintenance

Command	Description
`npm run dev:vinext`	Start the vinext development server.
`npm run build:vinext`	Test a production build.
`npx @vinext/cloudflare deploy`	Deploy the latest application to Workers.
`npx wrangler deployments list`	Show recent Worker deployments when supported by your configuration.
`npx wrangler tail`	Stream live Worker logs to investigate runtime errors.
`npx wrangler secret list`	Confirm production secret names exist.
`npx wrangler whoami`	Check Cloudflare authentication.
`npm list next`	Show the Next.js version.
`npx wrangler --version`	Show the Wrangler version.

4. Typical first deployment checklist

Ensure you are using a supported Next.js version and all dependencies install.
Run npx vinext check; resolve any unsupported APIs, native Node.js modules, or build errors.
Run npx vinext init; select Cloudflare Workers.
Create .dev.vars for local server secrets, if needed. Do not commit it.
Test with npm run dev:vinext, including login, database requests, and API routes.
Run npm run build:vinext and resolve production build errors.
Run npx @vinext/cloudflare deploy for the first deployment.
Add production secrets with npx wrangler secret put <NAME>; check with npx wrangler secret list. You can add them before first deploy if the target Worker already exists; otherwise deploy initially and add secrets, then verify/redeploy as needed.
For NEXT_PUBLIC_ values, ensure build-time values are correct and rebuild/redeploy after changing them.
Open the returned *.workers.dev URL and test actual production behavior, not just the homepage.

5. Common problems to check

Symptom	What to check
`Missing script: dev:vinext`	`vinext init` did not finish successfully or you're in the wrong directory; inspect `package.json`.
`Missing script: build:vinext`	Confirm initialization and the generated build script.
`Unauthorized` or account error	Run `npx wrangler login`, then `npx wrangler whoami`.
Environment variable is `undefined` on Cloudflare	Did you only set `.env.local` or `.dev.vars`? Add the production secret or Wrangler `vars` as appropriate.
Variable works server-side but not in the browser	Browser variables are public/build-time; verify `NEXT_PUBLIC_` and rebuild. Never send secrets to browser code.
Database doesn't connect	Verify driver and database are compatible with Workers, secrets are set, network/TLS rules allow access, and pooling is correct.
Build works but some routes fail	Check Cloudflare Worker logs using `npx wrangler tail` and review vinext compatibility.

Cloudflare Workers

Existing Next.js App → Cloudflare Workers: Command Reference

1. Required commands in order

2. Environment variables and secrets (.env / .dev.vars)

Environment commands

Prevent accidental Git commits

3. Build, release, diagnostics, and maintenance

4. Typical first deployment checklist

5. Common problems to check

Official documentation

Cloudflare Workers

Existing Next.js App → Cloudflare Workers: Command Reference

1. Required commands in order

2. Environment variables and secrets (.env / .dev.vars)

Environment commands

Prevent accidental Git commits

3. Build, release, diagnostics, and maintenance

4. Typical first deployment checklist

5. Common problems to check

Official documentation

2. Environment variables and secrets (`.env` / `.dev.vars`)

2. Environment variables and secrets (`.env` / `.dev.vars`)