From 157988a0fa917cffb93cfc4378c0d9560a8ac083 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 11:39:51 +0200 Subject: [PATCH 1/9] docs(cloudflare): add a section for CLI commands --- pages/cloudflare/_meta.json | 1 + pages/cloudflare/bindings.mdx | 3 +-- pages/cloudflare/caching.mdx | 20 +-------------- pages/cloudflare/cli.mdx | 35 ++++++++++++++++++++++++++ pages/cloudflare/get-started.mdx | 2 +- pages/cloudflare/howtos/dev-deploy.mdx | 16 +++--------- 6 files changed, 42 insertions(+), 35 deletions(-) create mode 100644 pages/cloudflare/cli.mdx diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index d00ded90..a1c8f1c7 100644 --- a/pages/cloudflare/_meta.json +++ b/pages/cloudflare/_meta.json @@ -1,6 +1,7 @@ { "index": "Overview", "get-started": "", + "cli": "cli (opennextjs-cloudflare)", "bindings": "", "caching": "", "howtos": "How-Tos", diff --git a/pages/cloudflare/bindings.mdx b/pages/cloudflare/bindings.mdx index 96bd2173..eb172db6 100644 --- a/pages/cloudflare/bindings.mdx +++ b/pages/cloudflare/bindings.mdx @@ -53,8 +53,7 @@ To ensure that your types are always up-to-date, make sure to run `wrangler type ## Local access to bindings -As presented in the [getting started](/cloudflare/get-started#12-develop-locally) your application can be both developed (`next dev`) and -previewed (`opennextjs-cloudflare preview`) locally, in both cases bindings will be accessible from your application's code. +As presented in the [getting started](/cloudflare/get-started#12-develop-locally) your application can be both developed (`next dev`) and [previewed locally](/cloudflare/cli#preview-command), in both cases bindings will be accessible from your application's code. Such bindings are by default local simulation that mimic the behavior of the actual Cloudflare resources. diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 6d1ab8b4..8ba58d87 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -585,25 +585,7 @@ export default defineCloudflareConfig({ In order for the cache to be properly initialised with the build-time revalidation data, you need to run a command as part of your deploy step. This should be run as part of each deployment to ensure that the cache is being populated with each build's data. -To populate remote bindings and create a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of your application at the same time, you can use either the `deploy` command or the `upload` command. Similarly, the `preview` command will populate your local bindings and start a Wrangler dev server. - -```sh -# Populate remote and deploy the worker immediately. -opennextjs-cloudflare deploy - -# Populate remote and upload a new version of the worker. -opennextjs-cloudflare upload - -# Populate local and start dev server. -opennextjs-cloudflare preview -``` - -It is possible to only populate the cache without any other steps with the `populateCache` command. - -```sh -# The target is passed as an option, either `local` or `remote`. -opennextjs-cloudflare populateCache local -``` +To populate remote bindings and create a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of your application at the same time, you can use either the [`deploy`](/cloudflare/cli#deploy-command) command or the [`upload`](/cloudflare/cli#upload-command) command. Similarly, the [`preview`](/cloudflare/cli#preview-command) command will populate your local bindings and start a Wrangler dev server. diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx new file mode 100644 index 00000000..9cdadf1c --- /dev/null +++ b/pages/cloudflare/cli.mdx @@ -0,0 +1,35 @@ +import { Callout } from "nextra/components"; + +## `opennextjs-cloudflare` CLI + +The cloudflare adapter provides a `opennextjs-cloudflare` CLI to develop, build, and deploy your application. You should not use `wrangler` commands directly unless documented otherwise or if you know what you are doing. + +## commands + +`opennextjs-cloudflare` support multiple commands, invoked via `opennextjs-cloudflare `. + +The currently supported commands are `build`, `populateCache`, `preview`, `deploy`, and `upload`. + +You can list the command by invoking `pnpm opennextjs-cloudflare` and get help with a given command by invoking `pnpm opennextjs-cloudflare --help`. + +Most commands take command specific options (i.e. `pnpm opennextjs-cloudflare build --skipNextBuild --noMinify`) and also accept wrangler options (i.e. `pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod`). + +### `build` command + +It first builds the Next.js application by invoking the `build` script of the `package.json` - which typically execute `next build`. It then runs the cloudflare specific build step to update the built files to run on the Cloudflare runtime. + +### `populateCache` command + +It populates the configured [Open Next cache components](/cloudflare/caching) so that caching works at runtime. It can populate the local bindings (`populateCache local`) used during development on your local machine or the remote bindings (`populateCache remote`) used by the deployed application. Note that this command is implicitely called by the `preview`, `deploy`, and `upload` commands so there is no need to explicitely call `populate` when one of those is used. + +### `preview` command + +It starts by populating the local cache and then launch a local developement server (via `wrangler dev`) so that you can preview the application locally. + +### `deploy` command + +It starts by populating the remote cache and then deploy your application to Cloudflare (via `wrangler deploy`). The application will start serving as soon as it is deployed. + +### `upload` command + +It starts by populating the remote cache and then upload a version of your application to Cloudflare (via `wrangler upload`). Note that the application will not automatically be served on uploads. See [Gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/) to learn more about how to serve an uploaded version. diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 050b8b3f..beb6e153 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -134,7 +134,7 @@ Add the following to the scripts field of your `package.json` file: "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts", ``` -- The `build` script must invoke the Next.js build command, it will be invoke by `opennextjs-cloudflare build`. +- The `build` script must invoke the Next.js build command, it will be invoked by [`opennextjs-cloudflare build`](/cloudflare/cli#build-command). - `npm run preview`: Builds your app and serves it locally, allowing you to quickly preview your app running locally in the Workers runtime, via a single command. - `npm run deploy`: Builds your app, and then immediately deploys it to Cloudflare. - `npm run upload`: Builds your app, and then uploads a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of it to Cloudflare. diff --git a/pages/cloudflare/howtos/dev-deploy.mdx b/pages/cloudflare/howtos/dev-deploy.mdx index d7ea61d9..f3e38a8c 100644 --- a/pages/cloudflare/howtos/dev-deploy.mdx +++ b/pages/cloudflare/howtos/dev-deploy.mdx @@ -42,15 +42,15 @@ initOpenNextCloudflareForDev(); #### Use `opennextjs-cloudflare` to build and test on the Workers runtime -After you've finished iterating on your Next.js application with `next dev`, you can convert it to a Cloudflare Worker by running the `opennextjs-cloudflare build` command. This will generate the Worker code in the `.open-next` directory. +After you've finished iterating on your Next.js application with `next dev`, you can convert it to a Cloudflare Worker by running the [`opennextjs-cloudflare build` command](/cloudflare/cli#build-command). This will generate the Worker code in the `.open-next` directory. You can then preview the app locally in the Cloudflare Workers runtime. -To preview your worker locally, run the `opennextjs-cloudflare preview` command. This will populate the cache and create a local server that runs your worker in the Cloudflare Workers runtime. Testing your worker is important to ensure that it has been properly built and is working as expected. +To preview your worker locally, run the [`opennextjs-cloudflare preview` command](/cloudflare/cli#preview-command). This will populate the cache and create a local server that runs your worker in the Cloudflare Workers runtime. Testing your worker is important to ensure that it has been properly built and is working as expected. ### Deploy your application to Cloudflare Workers -Both the `deploy` and `upload` commands of `opennextjs-cloudflare` can be used to deploy your application to cloudflare Workers. Both commands will initialize the remote cache and upload your application to the Cloudflare infrastructure. +Both the [`deploy`](/cloudflare/cli#deploy-command) and [`upload`](/cloudflare/cli#upload-command) commands of `opennextjs-cloudflare` can be used to deploy your application to cloudflare Workers. Both commands will initialize the remote cache and upload your application to the Cloudflare infrastructure. While `deploy` will start serving your application as soon as it is uploaded, `upload` only creates a new version of the application so that you can use [gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/). @@ -76,13 +76,3 @@ In the Build settings: - The "Build command" should be set to `npx opennextjs-cloudflare build`. - The "Deploy command" should be set to `npx opennextjs-cloudflare deploy` (or `upload` to use gradual deployments). - - - The `deploy`, `upload`, and `populateCache` commands of `opennextjs-cloudflare` invoke `wrangler`. - You can pass arguments to `wrangler` by specifying them after `--`: - -```sh -opennextjs-cloudflare deploy -- --env=prod -``` - - From 07c11443feef582d54de07552da57bef8328a56e Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:37:44 +0200 Subject: [PATCH 2/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index 9cdadf1c..70bf9e28 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -10,7 +10,7 @@ The cloudflare adapter provides a `opennextjs-cloudflare` CLI to develop, build, The currently supported commands are `build`, `populateCache`, `preview`, `deploy`, and `upload`. -You can list the command by invoking `pnpm opennextjs-cloudflare` and get help with a given command by invoking `pnpm opennextjs-cloudflare --help`. +You can list the commands by invoking `pnpm opennextjs-cloudflare` and get help with a given command by invoking `pnpm opennextjs-cloudflare --help`. Most commands take command specific options (i.e. `pnpm opennextjs-cloudflare build --skipNextBuild --noMinify`) and also accept wrangler options (i.e. `pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod`). From 3377a0688c4d35e713cb27e6430820af7a1dc0ba Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:37:51 +0200 Subject: [PATCH 3/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index 70bf9e28..f641fee4 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -2,7 +2,7 @@ import { Callout } from "nextra/components"; ## `opennextjs-cloudflare` CLI -The cloudflare adapter provides a `opennextjs-cloudflare` CLI to develop, build, and deploy your application. You should not use `wrangler` commands directly unless documented otherwise or if you know what you are doing. +The Cloudflare adapter provides a `opennextjs-cloudflare` CLI to develop, build, and deploy your application. You should not use `wrangler` commands directly unless documented otherwise or if you know what you are doing. ## commands From b1a86f7f74aa82fdab660a65c523cfbd769a7a18 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:37:59 +0200 Subject: [PATCH 4/9] Update pages/cloudflare/_meta.json Co-authored-by: James Anderson --- pages/cloudflare/_meta.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index a1c8f1c7..de316a15 100644 --- a/pages/cloudflare/_meta.json +++ b/pages/cloudflare/_meta.json @@ -1,7 +1,7 @@ { "index": "Overview", "get-started": "", - "cli": "cli (opennextjs-cloudflare)", + "cli": "CLI (opennextjs-cloudflare)", "bindings": "", "caching": "", "howtos": "How-Tos", From 685a8f69d68666e7f1798dc743fd16e4f78cfa4c Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:38:07 +0200 Subject: [PATCH 5/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index f641fee4..bc426848 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -16,7 +16,7 @@ Most commands take command specific options (i.e. `pnpm opennextjs-cloudflare bu ### `build` command -It first builds the Next.js application by invoking the `build` script of the `package.json` - which typically execute `next build`. It then runs the cloudflare specific build step to update the built files to run on the Cloudflare runtime. +It first builds the Next.js application by invoking the `build` script of the `package.json` - which typically execute `next build`. It then runs the Cloudflare specific build step to update the built files to run on the Cloudflare runtime. ### `populateCache` command From b0c07648f4eede3315edacb428c4071f35310133 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:38:15 +0200 Subject: [PATCH 6/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index bc426848..26da0f6d 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -20,7 +20,7 @@ It first builds the Next.js application by invoking the `build` script of the `p ### `populateCache` command -It populates the configured [Open Next cache components](/cloudflare/caching) so that caching works at runtime. It can populate the local bindings (`populateCache local`) used during development on your local machine or the remote bindings (`populateCache remote`) used by the deployed application. Note that this command is implicitely called by the `preview`, `deploy`, and `upload` commands so there is no need to explicitely call `populate` when one of those is used. +It populates the configured [Open Next cache components](/cloudflare/caching) so that caching works at runtime. It can populate the local bindings (`populateCache local`) used during development on your local machine or the remote bindings (`populateCache remote`) used by the deployed application. Note that this command is implicitly called by the `preview`, `deploy`, and `upload` commands so there is no need to explicitly call `populateCache` when one of those is used. ### `preview` command From d26e6b3f7995126814e2841b1afa427775c7232e Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:38:25 +0200 Subject: [PATCH 7/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index 26da0f6d..180713b0 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -24,7 +24,7 @@ It populates the configured [Open Next cache components](/cloudflare/caching) so ### `preview` command -It starts by populating the local cache and then launch a local developement server (via `wrangler dev`) so that you can preview the application locally. +It starts by populating the local cache and then launches a local development server (via `wrangler dev`) so that you can preview the application locally. ### `deploy` command From a2567b586af8ca82f0356c2555cf4ec1f60b3e1d Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:38:41 +0200 Subject: [PATCH 8/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index 180713b0..3c721cbc 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -32,4 +32,4 @@ It starts by populating the remote cache and then deploy your application to Clo ### `upload` command -It starts by populating the remote cache and then upload a version of your application to Cloudflare (via `wrangler upload`). Note that the application will not automatically be served on uploads. See [Gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/) to learn more about how to serve an uploaded version. +It starts by populating the remote cache and then uploads a version of your application to Cloudflare (via `wrangler upload`). Note that the application will not automatically be served on uploads. See [Gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/) to learn more about how to serve an uploaded version. From c9398f31d826db65fd8adcdd37b75f8906e3de77 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 6 Oct 2025 12:38:49 +0200 Subject: [PATCH 9/9] Update pages/cloudflare/cli.mdx Co-authored-by: James Anderson --- pages/cloudflare/cli.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/cli.mdx b/pages/cloudflare/cli.mdx index 3c721cbc..264680f2 100644 --- a/pages/cloudflare/cli.mdx +++ b/pages/cloudflare/cli.mdx @@ -28,7 +28,7 @@ It starts by populating the local cache and then launches a local development se ### `deploy` command -It starts by populating the remote cache and then deploy your application to Cloudflare (via `wrangler deploy`). The application will start serving as soon as it is deployed. +It starts by populating the remote cache and then deploys your application to Cloudflare (via `wrangler deploy`). The application will start serving as soon as it is deployed. ### `upload` command