From 17ffff68182ea2abdc761f10637721f657dbc6cf Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 31 Mar 2025 16:39:24 +0200 Subject: [PATCH 01/11] Updates Next Framework Guide for deploying on Workers --- .../frameworks/framework-guides/nextjs.mdx | 175 ++++++++++-------- 1 file changed, 97 insertions(+), 78 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 4d5ff34cab26790..fce17fbbac27765 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -6,24 +6,15 @@ description: Create an Next.js application and deploy it to Cloudflare Workers w --- import { - Badge, Description, - InlineBadge, + Details, Render, PackageManagers, - Stream, - WranglerConfig, + Steps, + WranglerConfig } from "~/components"; -In this guide, you will create a new [Next.js](https://nextjs.org/) application and deploy to Cloudflare Workers (with the new [ Workers Assets](/workers/static-assets/)) using the [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) package. - -:::note -If your Next.js app currently runs on Vercel, you can easily migrate your Next.js app to Cloudflare by using [Diverce](https://github.com/ygwyg/diverce), which will automatically add OpenNext to your project and create a pull request that makes it deployable to Cloudflare. -::: - -## New apps - -To create a new Next.js app, pre-configured to run on Cloudflare using [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), run: +**Start from CLI** - scaffold an Next.js project on Workers. - +:::note +This is a simple getting started guide for a more detailed documentation on how the to use the Cloudflare Open Next adapter visit the [Open Next website](https://opennext.js.org/cloudflare). +::: -## Existing Next.js apps +## What is Next.js -:::note[Minimum required Wrangler version: 3.99.0.] +[Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications. Think of React as the engine for building user interfaces (UIs) with components, while Next.js provides the chassis, structure, and additional features needed to build complete, production-ready web applications more easily and efficiently. -Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/). +Next.js uses hybrid rendering to allow different parts of the your application to be rendered either on the server or on the client. For instance, critical pages needing fast initial loads and strong SEO might be server-rendered for faster load while highly interactive sections might leverage client-side rendering for dynamic updates without requiring full page reloads. -::: +Next supports Partial Prerendering to combine static and dynamic components in the same route. -### 1. Install @opennextjs/cloudflare +## Deploy a new Next.js project on Workers -First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare): + -```sh -npm install --save-dev @opennextjs/cloudflare -``` +1. **Create a new project with the create-cloudflare CLI (C3).** + -### 2. Add a Wrangler configuration file +
+ When you run this command, C3 creates a new project directory, initiates [Next.js's official setup tool](https://nextjs.org/docs/app/api-reference/cli/create-next-app), and configures the project for Cloudflare. It then offers the option to instantly deploy your application to Cloudflare. +
-Then, add a [Wrangler configuration file](/workers/wrangler/configuration/) to the root directory of your Next.js app: +2. **Develop locally.** - + After creating your project, run the following command in your project directory to start a local development server. + The command uses the Next.js development server. It offers the best developer experience by quickly reloading your app every time the source code is updated. -```toml -main = ".open-next/worker.js" -name = "my-app" -compatibility_date = "2024-09-23" -compatibility_flags = ["nodejs_compat"] -assets = { directory = ".open-next/assets", binding = "ASSETS" } -``` + - +3. **Test your site with the Cloudflare adapter.** -:::note -As shown above, you must enable the [`nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/) _and_ set your [compatibility date](/workers/configuration/compatibility-dates/) to `2024-09-23` or later for your Next.js app to work with @opennextjs/cloudflare. -::: + The command used in the previous step uses the Next.js development server to offer a great developer experience. + However your application will run on Cloudflare Workers so you want to run your integration tests and verify that your application works correctly in this environment. -You configure your Worker and define what resources it can access via [bindings](/workers/runtime-apis/bindings/) in the [Wrangler configuration file](/workers/wrangler/configuration/). + -### 3. Update `package.json` +4. **Deploy your project.** -Add the following to the scripts field of your `package.json` file: + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. -```json -"preview": "opennextjs-cloudflare && wrangler dev", -"deploy": "opennextjs-cloudflare && wrangler deploy", -"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts" -``` + -- `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. -- `deploy`: Builds your app, and then deploys it to Cloudflare -- `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the root of your project containing the types for the env. + -### 4. Optionally add caching +## Deploy an existing Next.js project on Workers -Caching is actively being worked on. It is fully functional for development and we are working on an optimized implementation suitable for production. +You can convert an existing Next.js application to run on Cloudflare -For more details check the relevant [official Open Next documentation](https://opennext.js.org/cloudflare/caching). + -### 5. Develop locally +1. **Install [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare)** -You can continue to run `next dev` when developing locally. + -### 6. Preview locally your application and create an OpenNext config file +2. **Add a Wrangler configuration file** -In step 3, we also added the `npm run preview` script, 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 that your app runs in, when deployed to Cloudflare: + In your project root, create a [Wrangler configuration file](/workers/wrangler/configuration/) with the following content: -```sh -npm run preview -``` + + ```toml + main = ".open-next/worker.js" + name = "my-app" + compatibility_date = "2025-03-25" + compatibility_flags = ["nodejs_compat"] + assets = { directory = ".open-next/assets", binding = "ASSETS" } + ``` + -This command will build your OpenNext application, also creating, if not already present, an `open-next.configs.ts` file for you. -This is necessary if you want to deploy your application with a GibHub/GitLab integration as presented in the next step. + :::note + As shown above, you must enable the [`nodejs_compat` compatibility flag](/workers/runtime-apis/nodejs/) _and_ set your [compatibility date](/workers/configuration/compatibility-dates/) to `2024-09-23` or later for your Next.js app to work with @opennextjs/cloudflare. + ::: -### 7. Deploy to Cloudflare Workers +3. **Add a configuration file for OpenNext** -Either deploy via the command line: + In your project root, create an OpenNext configuration file name `open-next.config.ts` with the following content: -```sh -npm run deploy -``` + ```ts + import { defineCloudflareConfig } from "@opennextjs/cloudflare"; -Or [connect a GitHub or GitLab repository](/workers/ci-cd/), and Cloudflare will automatically build and deploy each pull request you merge to your production branch. + export default defineCloudflareConfig(); + ``` ---- + :::note + `open-next.config.ts` is where you can configure the caching, see the [adapter documentation](https://opennext.js.org/cloudflare/caching) for more information + ::: + +4. **Update `package.json`** + + You can add the following scripts to your `package.json`: + + ```json + "preview": "opennextjs-cloudflare && wrangler dev", + "deploy": "opennextjs-cloudflare && wrangler deploy", + "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts" + ``` + +
+ - `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. + - `deploy`: Builds your app, and then deploys it to Cloudflare + - `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the root of your project containing the types for the env. +
+ +5. **Develop locally.** + + After creating your project, run the following command in your project directory to start a local development server. + The command uses the Next.js development server. It offers the best developer experience by quickly reloading your app after your source code is updated. + + + +6. **Test your site with the Cloudflare adapter.** + + The command used in the previous step uses the Next.js development server to offer a great developer experience. + However your application will run on Cloudflare Workers so you want to run your integration tests and verify that your application workers correctly in this environment. + + + +7. **Deploy your project.** -## Static assets + You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. -You can serve static assets your Next.js application by placing them in the `./public/` directory. This can be useful for resource files such as images, stylesheets, fonts, and manifests. + - + From 16c92c885867268908c244deacded4b00837d237 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Wed, 2 Apr 2025 12:07:56 +0200 Subject: [PATCH 02/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index fce17fbbac27765..83aaa9494750296 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -23,7 +23,7 @@ import { /> :::note -This is a simple getting started guide for a more detailed documentation on how the to use the Cloudflare Open Next adapter visit the [Open Next website](https://opennext.js.org/cloudflare). +This is a simple getting started guide. For detailed documentation on how the to use the Cloudflare OpenNext adapter, visit the [OpenNext website](https://opennext.js.org/cloudflare). ::: ## What is Next.js From 09c68ee59dc76651529766d3d824d6f73ee388e3 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Wed, 2 Apr 2025 12:09:22 +0200 Subject: [PATCH 03/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 83aaa9494750296..1664e1e4a289c41 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -26,7 +26,7 @@ import { This is a simple getting started guide. For detailed documentation on how the to use the Cloudflare OpenNext adapter, visit the [OpenNext website](https://opennext.js.org/cloudflare). ::: -## What is Next.js +## What is Next.js? [Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications. Think of React as the engine for building user interfaces (UIs) with components, while Next.js provides the chassis, structure, and additional features needed to build complete, production-ready web applications more easily and efficiently. From 85d5fefd580b28226114428557aa9d6ff458486e Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Wed, 2 Apr 2025 12:09:33 +0200 Subject: [PATCH 04/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 1664e1e4a289c41..1e05ce71e2f911a 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -56,7 +56,7 @@ Next supports Partial Prerendering to combine static and dynamic components in t -3. **Test your site with the Cloudflare adapter.** +3. **Test and preview your site with the Cloudflare adapter.** The command used in the previous step uses the Next.js development server to offer a great developer experience. However your application will run on Cloudflare Workers so you want to run your integration tests and verify that your application works correctly in this environment. From 0ee7f732ef8f0b101b012afb38db51a6e1a18506 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Wed, 2 Apr 2025 12:10:14 +0200 Subject: [PATCH 05/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 1e05ce71e2f911a..4ccb8a4c4660d4f 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -101,7 +101,7 @@ You can convert an existing Next.js application to run on Cloudflare 3. **Add a configuration file for OpenNext** - In your project root, create an OpenNext configuration file name `open-next.config.ts` with the following content: + In your project root, create an OpenNext configuration file named `open-next.config.ts` with the following content: ```ts import { defineCloudflareConfig } from "@opennextjs/cloudflare"; From 1791dfd5a49d39a680efeb7fcacecdd9eb7ec90b Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 4 Apr 2025 10:22:24 +0200 Subject: [PATCH 06/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: emily-shen <69125074+emily-shen@users.noreply.github.com> --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 4ccb8a4c4660d4f..f489705e8f3b34d 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -28,7 +28,7 @@ This is a simple getting started guide. For detailed documentation on how the to ## What is Next.js? -[Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications. Think of React as the engine for building user interfaces (UIs) with components, while Next.js provides the chassis, structure, and additional features needed to build complete, production-ready web applications more easily and efficiently. +[Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications. Next.js uses hybrid rendering to allow different parts of the your application to be rendered either on the server or on the client. For instance, critical pages needing fast initial loads and strong SEO might be server-rendered for faster load while highly interactive sections might leverage client-side rendering for dynamic updates without requiring full page reloads. From 4dd0d091c64d6762e633e23aeb9fea277837327d Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 4 Apr 2025 10:58:17 +0200 Subject: [PATCH 07/11] fixup! feedback --- .../workers/frameworks/framework-guides/nextjs.mdx | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index f489705e8f3b34d..6fc07e1c9c7d865 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -30,9 +30,9 @@ This is a simple getting started guide. For detailed documentation on how the to [Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications. -Next.js uses hybrid rendering to allow different parts of the your application to be rendered either on the server or on the client. For instance, critical pages needing fast initial loads and strong SEO might be server-rendered for faster load while highly interactive sections might leverage client-side rendering for dynamic updates without requiring full page reloads. +Next.js supports Server-side and Client-side rendering, as well as Partial Prerendering which lets you combine static and dynamic components in the same route. -Next supports Partial Prerendering to combine static and dynamic components in the same route. +You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor. ## Deploy a new Next.js project on Workers @@ -58,11 +58,14 @@ Next supports Partial Prerendering to combine static and dynamic components in t 3. **Test and preview your site with the Cloudflare adapter.** - The command used in the previous step uses the Next.js development server to offer a great developer experience. - However your application will run on Cloudflare Workers so you want to run your integration tests and verify that your application works correctly in this environment. - + + The command used in the previous step uses the Next.js development server, which runs in Node.js. + However, your deployed application will run on Cloudflare Workers, which uses the `workerd` runtime. Therefore when running integration tests and previewing your application, you should use the preview command, which is more accurate to production, as it executes your application in the `workerd` runtime using `wrangler dev`. + + + 4. **Deploy your project.** You can deploy your project to a [`*.workers.dev` subdomain](/workers/configuration/routing/workers-dev/) or a [custom domain](/workers/configuration/routing/custom-domains/) from your local machine or any CI/CD system (including [Workers Builds](/workers/ci-cd/#workers-builds)). Use the following command to build and deploy. If you're using a CI service, be sure to update your "deploy command" accordingly. From 786a0a4e255f54ec536a7fe97f2a43ff9fc9d0c9 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 4 Apr 2025 11:06:15 +0200 Subject: [PATCH 08/11] fixup! update scripts --- .../docs/workers/frameworks/framework-guides/nextjs.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 6fc07e1c9c7d865..d7a41c2b9e7098b 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -39,6 +39,7 @@ You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor 1. **Create a new project with the create-cloudflare CLI (C3).** + Date: Fri, 4 Apr 2025 11:20:32 +0200 Subject: [PATCH 09/11] fixup! Detail -> Details --- .../docs/workers/frameworks/framework-guides/nextjs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index d7a41c2b9e7098b..86e8ad527ddeecb 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -61,10 +61,10 @@ You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor - +
The command used in the previous step uses the Next.js development server, which runs in Node.js. However, your deployed application will run on Cloudflare Workers, which uses the `workerd` runtime. Therefore when running integration tests and previewing your application, you should use the preview command, which is more accurate to production, as it executes your application in the `workerd` runtime using `wrangler dev`. - +
4. **Deploy your project.** From 298516718b855f11e25c4bd308dc0d3c754f32a2 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Fri, 4 Apr 2025 11:34:57 +0200 Subject: [PATCH 10/11] fixup! Details#header --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 86e8ad527ddeecb..4fd489213ae3737 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -61,7 +61,7 @@ You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor -
+
The command used in the previous step uses the Next.js development server, which runs in Node.js. However, your deployed application will run on Cloudflare Workers, which uses the `workerd` runtime. Therefore when running integration tests and previewing your application, you should use the preview command, which is more accurate to production, as it executes your application in the `workerd` runtime using `wrangler dev`.
From 2ba48e25a45e4bc4893bd8a1a5bc9d4a0c2b5fa9 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Tue, 8 Apr 2025 10:55:29 +0200 Subject: [PATCH 11/11] Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: Pete Bacon Darwin --- src/content/docs/workers/frameworks/framework-guides/nextjs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx index 4fd489213ae3737..a39325e4f49abd2 100644 --- a/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx +++ b/src/content/docs/workers/frameworks/framework-guides/nextjs.mdx @@ -14,7 +14,7 @@ import { WranglerConfig } from "~/components"; -**Start from CLI** - scaffold an Next.js project on Workers. +**Start from CLI** - scaffold a Next.js project on Workers.