Skip to content

Commit ae8c2ce

Browse files
vicbemily-shenpetebacondarwin
authored
Updates Next Framework Guide for deploying on Workers (#21256)
Co-authored-by: emily-shen <[email protected]> Co-authored-by: Pete Bacon Darwin <[email protected]>
1 parent 381401a commit ae8c2ce

File tree

1 file changed

+101
-78
lines changed
  • src/content/docs/workers/frameworks/framework-guides

1 file changed

+101
-78
lines changed

‎src/content/docs/workers/frameworks/framework-guides/nextjs.mdx‎

Lines changed: 101 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -6,128 +6,151 @@ description: Create an Next.js application and deploy it to Cloudflare Workers w
66
---
77

88
import {
9-
Badge,
109
Description,
11-
InlineBadge,
10+
Details,
1211
Render,
1312
PackageManagers,
14-
Stream,
15-
WranglerConfig,
13+
Steps,
14+
WranglerConfig
1615
} from "~/components";
1716

18-
In this guide, you will create a new [Next.js](https://nextjs.org/) application and deploy to Cloudflare Workers (with the new [<InlineBadge preset="beta" /> Workers Assets](/workers/static-assets/)) using the [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) package.
19-
20-
:::note
21-
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.
22-
:::
23-
24-
## New apps
25-
26-
To create a new Next.js app, pre-configured to run on Cloudflare using [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), run:
17+
**Start from CLI** - scaffold a Next.js project on Workers.
2718

2819
<PackageManagers
2920
type="create"
3021
pkg="cloudflare@latest my-next-app"
3122
args={"--framework=next --platform=workers"}
3223
/>
3324

34-
<Render
35-
file="c3-post-run-steps"
36-
product="workers"
37-
params={{
38-
category: "web-framework",
39-
framework: "Next.js",
40-
}}
41-
/>
25+
:::note
26+
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).
27+
:::
4228

43-
## Existing Next.js apps
29+
## What is Next.js?
4430

45-
:::note[Minimum required Wrangler version: 3.99.0.]
31+
[Next.js](https://nextjs.org/) is a [React](https://react.dev/) framework for building full stack applications.
4632

47-
Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
33+
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.
4834

49-
:::
35+
You can deploy your Next.js app to Cloudflare Workers using the OpenNext adaptor.
5036

51-
### 1. Install @opennextjs/cloudflare
37+
## Deploy a new Next.js project on Workers
5238

53-
First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare):
39+
<Steps>
5440

55-
```sh
56-
npm install --save-dev @opennextjs/cloudflare
57-
```
41+
1. **Create a new project with the create-cloudflare CLI (C3).**
5842

59-
### 2. Add a Wrangler configuration file
43+
<PackageManagers
44+
type="create"
45+
pkg="cloudflare@latest my-next-app"
46+
args={"--framework=next --platform=workers"}
47+
/>
6048

61-
Then, add a [Wrangler configuration file](/workers/wrangler/configuration/) to the root directory of your Next.js app:
49+
<Details header="What's happening behind the scenes?">
50+
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.
51+
</Details>
6252

63-
<WranglerConfig>
53+
2. **Develop locally.**
6454

65-
```toml
66-
main = ".open-next/worker.js"
67-
name = "my-app"
68-
compatibility_date = "2024-09-23"
69-
compatibility_flags = ["nodejs_compat"]
70-
assets = { directory = ".open-next/assets", binding = "ASSETS" }
71-
```
55+
After creating your project, run the following command in your project directory to start a local development server.
56+
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.
7257

73-
</WranglerConfig>
58+
<PackageManagers type="run" args="dev" />
7459

75-
:::note
76-
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.
77-
:::
60+
3. **Test and preview your site with the Cloudflare adapter.**
7861

79-
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/).
62+
<PackageManagers type="run" args="preview" />
8063

81-
### 3. Update `package.json`
64+
<Details header="What's the difference between dev and preview?">
65+
The command used in the previous step uses the Next.js development server, which runs in Node.js.
66+
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`.
67+
</Details>
8268

83-
Add the following to the scripts field of your `package.json` file:
8469

85-
```json
86-
"preview": "opennextjs-cloudflare && wrangler dev",
87-
"deploy": "opennextjs-cloudflare && wrangler deploy",
88-
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
89-
```
70+
4. **Deploy your project.**
9071

91-
- `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.
92-
- `deploy`: Builds your app, and then deploys it to Cloudflare
93-
- `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the root of your project containing the types for the env.
72+
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.
9473

95-
### 4. Optionally add caching
74+
<PackageManagers type="run" args="deploy" />
9675

97-
Caching is actively being worked on. It is fully functional for development and we are working on an optimized implementation suitable for production.
76+
</Steps>
9877

99-
For more details check the relevant [official Open Next documentation](https://opennext.js.org/cloudflare/caching).
78+
## Deploy an existing Next.js project on Workers
10079

101-
### 5. Develop locally
80+
You can convert an existing Next.js application to run on Cloudflare
10281

103-
You can continue to run `next dev` when developing locally.
82+
<Steps>
10483

105-
### 6. Preview locally your application and create an OpenNext config file
84+
1. **Install [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare)**
10685

107-
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.
108-
This allows you to test changes in the same runtime that your app runs in, when deployed to Cloudflare:
86+
<PackageManagers type="install" pkg="@opennextjs/cloudflare@latest" />
10987

110-
```sh
111-
npm run preview
112-
```
88+
2. **Add a Wrangler configuration file**
11389

114-
This command will build your OpenNext application, also creating, if not already present, an `open-next.configs.ts` file for you.
115-
This is necessary if you want to deploy your application with a GibHub/GitLab integration as presented in the next step.
90+
In your project root, create a [Wrangler configuration file](/workers/wrangler/configuration/) with the following content:
11691

117-
### 7. Deploy to Cloudflare Workers
92+
<WranglerConfig>
93+
```toml
94+
main = ".open-next/worker.js"
95+
name = "my-app"
96+
compatibility_date = "2025-03-25"
97+
compatibility_flags = ["nodejs_compat"]
98+
assets = { directory = ".open-next/assets", binding = "ASSETS" }
99+
```
100+
</WranglerConfig>
118101

119-
Either deploy via the command line:
102+
:::note
103+
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.
104+
:::
120105

121-
```sh
122-
npm run deploy
123-
```
106+
3. **Add a configuration file for OpenNext**
124107

125-
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.
108+
In your project root, create an OpenNext configuration file named `open-next.config.ts` with the following content:
126109

127-
---
110+
```ts
111+
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
112+
113+
export default defineCloudflareConfig();
114+
```
115+
116+
:::note
117+
`open-next.config.ts` is where you can configure the caching, see the [adapter documentation](https://opennext.js.org/cloudflare/caching) for more information
118+
:::
119+
120+
4. **Update `package.json`**
121+
122+
You can add the following scripts to your `package.json`:
123+
124+
```json
125+
"preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
126+
"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
127+
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
128+
```
129+
130+
<Details header="Usage">
131+
- `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.
132+
- `deploy`: Builds your app, and then deploys it to Cloudflare
133+
- `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the root of your project containing the types for the env.
134+
</Details>
135+
136+
5. **Develop locally.**
137+
138+
After creating your project, run the following command in your project directory to start a local development server.
139+
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.
140+
141+
<PackageManagers type="run" args="dev" />
142+
143+
6. **Test your site with the Cloudflare adapter.**
144+
145+
The command used in the previous step uses the Next.js development server to offer a great developer experience.
146+
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.
147+
148+
<PackageManagers type="run" args="preview" />
149+
150+
7. **Deploy your project.**
128151

129-
## Static assets
152+
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.
130153

131-
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.
154+
<PackageManagers type="run" args="deploy" />
132155

133-
<Render file="workers-assets-routing-summary" />
156+
</Steps>

0 commit comments

Comments
 (0)