From 6b1aabc931ddc729521e40e20c00df36efb72a70 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Thu, 13 Mar 2025 16:00:34 +0100 Subject: [PATCH] [cloudflare] add howto dev workflow Co-authored-by: Dario Piotrowicz --- pages/cloudflare/get-started.mdx | 27 +++++++++-------- pages/cloudflare/howtos/_meta.json | 3 +- pages/cloudflare/howtos/dev.mdx | 47 ++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+), 15 deletions(-) create mode 100644 pages/cloudflare/howtos/dev.mdx diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 6cb4517..8a7c29e 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -7,7 +7,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` @@ -25,7 +25,7 @@ npm install --save-dev @opennextjs/cloudflare@latest Install the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) as a devDependency: -```npm +```sh npm install --save-dev wrangler@latest ``` @@ -157,26 +157,25 @@ This includes: You can continue to run `next dev` when developing locally. Modify your Next.js configuration file to import and call the `initOpenNextCloudflareForDev` utility -from the `@opennextjs/cloudflare` package. This makes sure that the Next.js dev server can optimally integrate with the open-next -cloudflare adapter and it is necessary for using bindings during local development. +from the `@opennextjs/cloudflare` package. This makes sure that the Next.js dev server can optimally integrate with the open-next cloudflare adapter and it is necessary for using bindings during local development. This is an example of a Next.js configuration file calling the utility: -```js -// next.config.mjs - -import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; - -initOpenNextCloudflareForDev(); +```ts +// next.config.ts +import type { NextConfig } from "next"; -/** @type {import('next').NextConfig} */ -const nextConfig = {}; +const nextConfig: NextConfig = { + /* config options here */ +}; export default nextConfig; + +import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; +initOpenNextCloudflareForDev(); ``` -After having added the `initOpenNextCloudflareForDev()` call in your Next.js configuration file, you will be able, during local -development, to access in any of your server code, local versions of Cloudflare bindings as indicated in the [bindings documentation](./bindings). +After having added the `initOpenNextCloudflareForDev()` call in your Next.js configuration file, you will be able, during local development, to access in any of your server code, local versions of Cloudflare bindings as indicated in the [bindings documentation](./bindings). In step 3, we also added the `npm run preview`, which allows you to quickly preview your app running locally in the Workers runtime, rather than in Node.js. This allows you to test changes in the same runtime as your app will run in when deployed to Cloudflare. diff --git a/pages/cloudflare/howtos/_meta.json b/pages/cloudflare/howtos/_meta.json index 1676dce..5bc5e65 100644 --- a/pages/cloudflare/howtos/_meta.json +++ b/pages/cloudflare/howtos/_meta.json @@ -1,4 +1,5 @@ { "NextAuth": "NextAuth", - "stripeAPI": "Stripe API" + "stripeAPI": "Stripe API", + "dev": "Development workflow" } diff --git a/pages/cloudflare/howtos/dev.mdx b/pages/cloudflare/howtos/dev.mdx new file mode 100644 index 0000000..a8a901f --- /dev/null +++ b/pages/cloudflare/howtos/dev.mdx @@ -0,0 +1,47 @@ +## 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 --experimental +``` + +### 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` 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.