opennextjs · james-elicx · Mar 21, 2025 · Mar 3, 2025 · Mar 4, 2025 · Mar 4, 2025
diff --git a/.changeset/silly-jokes-hammer.md b/.changeset/silly-jokes-hammer.md
@@ -0,0 +1,12 @@
+---
+"@opennextjs/cloudflare": minor
+---
+
+feat: commands for cli actions
+
+The OpenNext Cloudflare CLI now uses the following commands;
+
+- `build`: build the application
+- `populateCache`: populate either the local or remote cache
+- `preview`: populate the local cache and start a dev server
+- `deploy`: populate the remote cache and deploy to production
diff --git a/examples/bugs/gh-119/package.json b/examples/bugs/gh-119/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv"
   },

diff --git a/examples/bugs/gh-219/package.json b/examples/bugs/gh-219/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm run build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "deploy:worker": "pnpm run build:worker && pnpm wrangler deploy"
   },

diff --git a/examples/bugs/gh-223/package.json b/examples/bugs/gh-223/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm run build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "deploy:worker": "pnpm run build:worker && pnpm wrangler deploy"
   },

diff --git a/examples/common/config-e2e.ts b/examples/common/config-e2e.ts
@@ -25,11 +25,11 @@ export function configurePlaywright(
   if (isWorker) {
     if (isCI) {
       // Do not build on CI - there is a preceding build step
-      command = `pnpm wrangler dev --port ${port} --inspector-port ${inspectorPort}`;
+      command = `pnpm preview:worker -- --port ${port} --inspector-port ${inspectorPort}`;
       timeout = 100_000;
     } else {
       timeout = 500_000;
-      command = `pnpm preview --port ${port} --inspector-port ${inspectorPort}`;
+      command = `pnpm preview -- --port ${port} --inspector-port ${inspectorPort}`;
     }
   } else {
     timeout = 100_000;

diff --git a/examples/create-next-app/package.json b/examples/create-next-app/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/e2e/app-pages-router/package.json b/examples/e2e/app-pages-router/package.json
@@ -9,8 +9,9 @@
     "start": "next start --port 3003",
     "lint": "next lint",
     "clean": "rm -rf .turbo node_modules .next .open-next",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/e2e/app-router/package.json b/examples/e2e/app-router/package.json
@@ -10,8 +10,9 @@
     "lint": "next lint",
     "clean": "rm -rf .turbo node_modules .next .open-next",
     "d1:clean": "wrangler d1 execute NEXT_CACHE_D1 --command \"DROP TABLE IF EXISTS tags; DROP TABLE IF EXISTS revalidations\"",
-    "build:worker": "pnpm d1:clean && pnpm opennextjs-cloudflare --populateCache=local",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm d1:clean && pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/e2e/pages-router/package.json b/examples/e2e/pages-router/package.json
@@ -9,8 +9,9 @@
     "start": "next start --port 3002",
     "lint": "next lint",
     "clean": "rm -rf .turbo node_modules .next .open-next",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/middleware/package.json b/examples/middleware/package.json
@@ -6,8 +6,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "e2e:dev": "playwright test -c e2e/playwright.dev.config.ts"
   },

diff --git a/examples/next-partial-prerendering/package.json b/examples/next-partial-prerendering/package.json
@@ -5,8 +5,9 @@
     "build": "next build",
     "dev": "next dev --turbo",
     "start": "next start",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev"
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker"
   },
   "dependencies": {
     "@heroicons/react": "2.1.5",

diff --git a/examples/overrides/d1-tag-next/package.json b/examples/overrides/d1-tag-next/package.json
@@ -9,8 +9,9 @@
     "lint": "next lint",
     "d1:clean": "wrangler d1 execute NEXT_CACHE_D1 --command \"DROP TABLE IF EXISTS revalidations\"",
     "d1:setup": "wrangler d1 execute NEXT_CACHE_D1 --command \"CREATE TABLE IF NOT EXISTS revalidations (tag TEXT NOT NULL, revalidatedAt INTEGER NOT NULL, UNIQUE(tag) ON CONFLICT REPLACE);\"",
-    "build:worker": "opennextjs-cloudflare && pnpm d1:clean && pnpm d1:setup",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm d1:clean && pnpm opennextjs-cloudflare build && pnpm d1:setup",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/overrides/memory-queue/package.json b/examples/overrides/memory-queue/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/overrides/r2-incremental-cache/package.json b/examples/overrides/r2-incremental-cache/package.json
@@ -8,8 +8,9 @@
     "start": "next start",
     "lint": "next lint",
     "d1:clean": "wrangler d1 execute NEXT_CACHE_D1 --command \"DROP TABLE IF EXISTS tags; DROP TABLE IF EXISTS revalidations\"",
-    "build:worker": "pnpm d1:clean && pnpm opennextjs-cloudflare --populateCache=local",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm d1:clean && pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/playground14/package.json b/examples/playground14/package.json
@@ -8,8 +8,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "e2e:dev": "playwright test -c e2e/playwright.dev.config.ts",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv"

diff --git a/examples/playground15/package.json b/examples/playground15/package.json
@@ -8,8 +8,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "pnpm opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts",
     "e2e:dev": "playwright test -c e2e/playwright.dev.config.ts",
     "cf-typegen": "wrangler types --env-interface CloudflareEnv"

diff --git a/examples/ssg-app/package.json b/examples/ssg-app/package.json
@@ -7,8 +7,9 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev",
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker",
     "e2e": "playwright test -c e2e/playwright.config.ts"
   },
   "dependencies": {

diff --git a/examples/vercel-blog-starter/package.json b/examples/vercel-blog-starter/package.json
@@ -5,8 +5,9 @@
     "dev": "next",
     "build": "next build",
     "start": "next start",
-    "build:worker": "opennextjs-cloudflare",
-    "preview": "pnpm build:worker && pnpm wrangler dev"
+    "build:worker": "pnpm opennextjs-cloudflare build",
+    "preview:worker": "pnpm opennextjs-cloudflare preview",
+    "preview": "pnpm build:worker && pnpm preview:worker"
   },
   "dependencies": {
     "classnames": "^2.5.1",

diff --git a/examples/vercel-commerce/package.json b/examples/vercel-commerce/package.json
@@ -12,8 +12,9 @@
     "prettier": "prettier --write --ignore-unknown .",
     "prettier:check": "prettier --check --ignore-unknown .",
     "test": "pnpm prettier:check",
-    "tofix-build:worker": "opennextjs-cloudflare",
-    "tofix-preview": "pnpm build:worker && pnpm wrangler dev"
+    "tofix-build:worker": "pnpm opennextjs-cloudflare build",
+    "tofix-preview:worker": "pnpm opennextjs-cloudflare preview",
+    "tofix-preview": "pnpm build:worker && pnpm preview:worker"
   },
   "dependencies": {
     "@headlessui/react": "^2.1.2",

diff --git a/packages/cloudflare/README.md b/packages/cloudflare/README.md
@@ -19,13 +19,13 @@ Run the following commands to preview the production build of your application l
 - build the app and adapt it for Cloudflare
 
   ```bash
-  npx opennextjs-cloudflare
+  npx opennextjs-cloudflare build
   # or
-  pnpm opennextjs-cloudflare
+  pnpm opennextjs-cloudflare build
   # or
-  yarn opennextjs-cloudflare
+  yarn opennextjs-cloudflare build
   # or
-  bun opennextjs-cloudflare
+  bun opennextjs-cloudflare build
   ```
 
 - Preview the app in Wrangler
@@ -47,11 +47,11 @@ Deploy your application to production with the following:
 - build the app and adapt it for Cloudflare
 
   ```bash
-  npx opennextjs-cloudflare && npx wrangler deploy
+  npx opennextjs-cloudflare build && npx opennextjs-cloudflare deploy
   # or
-  pnpm opennextjs-cloudflare && pnpm wrangler deploy
+  pnpm opennextjs-cloudflare build && pnpm opennextjs-cloudflare deploy
   # or
-  yarn opennextjs-cloudflare && yarn wrangler deploy
+  yarn opennextjs-cloudflare build && yarn opennextjs-cloudflare deploy
   # or
-  bun opennextjs-cloudflare && bun wrangler deploy
+  bun opennextjs-cloudflare build && bun opennextjs-cloudflare deploy
   ```
diff --git a/packages/cloudflare/src/cli/args.ts b/packages/cloudflare/src/cli/args.ts
@@ -2,71 +2,61 @@ import { mkdirSync, type Stats, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 
-import type { CacheBindingMode } from "./build/utils/index.js";
-import { isCacheBindingMode } from "./build/utils/index.js";
+import { isWranglerTarget, WranglerTarget } from "./utils/run-wrangler.js";
 
-export function getArgs(): {
-  skipNextBuild: boolean;
-  skipWranglerConfigCheck: boolean;
-  outputDir?: string;
-  minify: boolean;
-  populateCache?: { mode: CacheBindingMode; onlyPopulateWithoutBuilding: boolean };
-} {
-  const { skipBuild, skipWranglerConfigCheck, output, noMinify, populateCache, onlyPopulateCache } =
-    parseArgs({
-      options: {
-        skipBuild: {
-          type: "boolean",
-          short: "s",
-          default: false,
-        },
-        output: {
-          type: "string",
-          short: "o",
-        },
-        noMinify: {
-          type: "boolean",
-          default: false,
-        },
-        skipWranglerConfigCheck: {
-          type: "boolean",
-          default: false,
-        },
-        populateCache: {
-          type: "string",
-        },
-        onlyPopulateCache: {
-          type: "boolean",
-          default: false,
-        },
-      },
-      allowPositionals: false,
-    }).values;
+export type Arguments = (
+  | {
+      command: "build";
+      skipNextBuild: boolean;
+      skipWranglerConfigCheck: boolean;
+      minify: boolean;
+    }
+  | { command: "preview" | "deploy"; passthroughArgs: string[] }
+  | { command: "populateCache"; target: WranglerTarget }
+) & { outputDir?: string };
 
-  const outputDir = output ? resolve(output) : undefined;
+export function getArgs(): Arguments {
+  const { positionals, values } = parseArgs({
+    options: {
+      skipBuild: { type: "boolean", short: "s", default: false },
+      output: { type: "string", short: "o" },
+      noMinify: { type: "boolean", default: false },
+      skipWranglerConfigCheck: { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
 
-  if (outputDir) {
-    assertDirArg(outputDir, "output", true);
-  }
+  const outputDir = values.output ? resolve(values.output) : undefined;
+  if (outputDir) assertDirArg(outputDir, "output", true);
 
-  if (
-    (populateCache !== undefined || onlyPopulateCache) &&
-    (!populateCache?.length || !isCacheBindingMode(populateCache))
-  ) {
-    throw new Error(`Error: missing mode for populate cache flag, expected 'local' | 'remote'`);
+  switch (positionals[0]) {
+    case "build":
+      return {
+        command: "build",
+        outputDir,
+        skipNextBuild:
+          values.skipBuild || ["1", "true", "yes"].includes(String(process.env.SKIP_NEXT_APP_BUILD)),
+        skipWranglerConfigCheck:
+          values.skipWranglerConfigCheck ||
+          ["1", "true", "yes"].includes(String(process.env.SKIP_WRANGLER_CONFIG_CHECK)),
+        minify: !values.noMinify,
+      };
+    case "preview":
+    case "deploy":
+      return { command: positionals[0], outputDir, passthroughArgs: getPassthroughArgs() };
+    case "populateCache":
+      if (!isWranglerTarget(positionals[1])) {
+        throw new Error(`Error: invalid target for populating the cache, expected 'local' | 'remote'`);
+      }
+      return { command: "populateCache", outputDir, target: positionals[1] };
+    default:
+      throw new Error("Error: invalid command, expected 'build' | 'preview' | 'deploy' | 'populateCache'");
   }
+}
 
-  return {
-    outputDir,
-    skipNextBuild: skipBuild || ["1", "true", "yes"].includes(String(process.env.SKIP_NEXT_APP_BUILD)),
-    skipWranglerConfigCheck:
-      skipWranglerConfigCheck ||
-      ["1", "true", "yes"].includes(String(process.env.SKIP_WRANGLER_CONFIG_CHECK)),
-    minify: !noMinify,
-    populateCache: populateCache
-      ? { mode: populateCache, onlyPopulateWithoutBuilding: !!onlyPopulateCache }
-      : undefined,
-  };
+function getPassthroughArgs() {
+  const passthroughPos = process.argv.indexOf("--");
+  return passthroughPos === -1 ? [] : process.argv.slice(passthroughPos + 1);
 }
 
 function assertDirArg(path: string, argName?: string, make?: boolean) {