diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index d00ded9..de316a1 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 96bd217..eb172db 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 6d1ab8b..8ba58d8 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 0000000..264680f --- /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 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`). + +### `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 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 + +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 + +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 + +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. diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 050b8b3..beb6e15 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 d7ea61d..f3e38a8 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 -``` - -