diff --git a/pages/cloudflare/howtos/_meta.json b/pages/cloudflare/howtos/_meta.json index e4803ff..3616fcb 100644 --- a/pages/cloudflare/howtos/_meta.json +++ b/pages/cloudflare/howtos/_meta.json @@ -1,7 +1,7 @@ { "NextAuth": "NextAuth", "stripeAPI": "Stripe API", - "dev": "Development workflow", + "dev-deploy": "Develop and Deploy", "env-vars": "Enviroment Variables", "image": "Image Optimization" } diff --git a/pages/cloudflare/howtos/dev-deploy.mdx b/pages/cloudflare/howtos/dev-deploy.mdx new file mode 100644 index 0000000..d7ea61d --- /dev/null +++ b/pages/cloudflare/howtos/dev-deploy.mdx @@ -0,0 +1,88 @@ +import { Callout } from "nextra/components"; + +## Develop and deploy + +### Development workflow + +The primary purpose of `@opennextjs/cloudflare` is to take a Next.js application, built with standard Next.js tooling, and convert it into a format compatible with Cloudflare Workers. + +This code transformation process takes some time, making the adapter less than ideal for active application development, where a very fast feedback loop and other quality-of-life features, such as Hot Module Replacement (HMR), are crucial. Fortunately, Vercel already provides excellent tooling for this workflow, which Next.js developers are likely already familiar with. + +We recommend that developers continue using the tools they are already comfortable with for local development and then use `@opennextjs/cloudflare` when they are ready to deploy their applications to the Cloudflare platform. + +Let's explore, in more detail, the application development workflow we recommend for the best developer experience. + +#### Create a new application based on a template + +To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: + +```bash +npm create cloudflare@latest -- my-next-app --framework=next --platform=workers +``` + +#### Develop locally using `next dev` + +We believe that the best development workflow uses the `next dev` command provided by Next.js. + +To access Cloudflare resources using the `getCloudflareContext` API while running `next dev`, you will need to update the Next.js configuration to call `initOpenNextCloudflareForDev`, as shown in the following example: + +```ts +// next.config.ts +import type { NextConfig } from "next"; + +const nextConfig: NextConfig = { + /* config options here */ +}; + +export default nextConfig; + +import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; +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. + +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. + +### 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. + +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/). + +#### Local build + +Use the `build` command followed by either `deploy` or `upload` to deploy your local build. + + + When running the `build` command locally, `.dev.vars` and [Next `.env` + files](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables) might + override your configuration. It is preferreable to use a CD system as [Workers + Builds](https://developers.cloudflare.com/workers/ci-cd/builds/) to deploy your application for reproducible + deployments. + + +#### Workers Builds + +When using Workers Builds, make sure to setup your environment variables as explained in [this guide](https://opennext.js.org/cloudflare/howtos/env-vars#production). + +You can then connect your GitHub repository by following [the documentation](https://developers.cloudflare.com/workers/ci-cd/builds/git-integration/). + +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 +``` + + diff --git a/pages/cloudflare/howtos/dev.mdx b/pages/cloudflare/howtos/dev.mdx deleted file mode 100644 index bced793..0000000 --- a/pages/cloudflare/howtos/dev.mdx +++ /dev/null @@ -1,47 +0,0 @@ -## Development Workflow - -The primary purpose of `@opennextjs/cloudflare` is to take a Next.js application, built with standard Next.js tooling, and convert it into a format compatible with Cloudflare Workers. - -This code transformation process takes some time, making the adapter less than ideal for active application development, where a very fast feedback loop and other quality-of-life features, such as Hot Module Replacement (HMR), are crucial. Fortunately, Vercel already provides excellent tooling for this workflow, which Next.js developers are likely already familiar with. - -We recommend that developers continue using the tools they are already comfortable with for local development and then use `@opennextjs/cloudflare` when they are ready to deploy their applications to the Cloudflare platform. - -Let's explore, in more detail, the application development workflow we recommend for the best developer experience. - -### Create a new application based on a template - -To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: - -```bash -npm create cloudflare@latest -- my-next-app --framework=next --platform=workers -``` - -### Develop locally using `next dev` - -We believe that the best development workflow uses the `next dev` command provided by Next.js. - -To access Cloudflare resources using the `getCloudflareContext` API while running `next dev`, you will need to update the Next.js configuration to call `initOpenNextCloudflareForDev`, as shown in the following example: - -```ts -// next.config.ts -import type { NextConfig } from "next"; - -const nextConfig: NextConfig = { - /* config options here */ -}; - -export default nextConfig; - -import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; -initOpenNextCloudflareForDev(); -``` - -### `wrangler dev` and `wrangler deploy` - -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. - -You can then preview the app locally in the Cloudflare Workers runtime or deploy it to the Cloudflare network. - -To preview your worker locally, run the `wrangler dev` command. This creates 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. - -Once you've tested your worker, You can run `wrangler deploy`, and in a matter of seconds, your masterpiece will be available to all your users around the world.