Skip to content

Commit 8a599b1

Browse files
vicbvicb
committed
Updates Next Framework Guide for deploying on Workers
1 parent dfb2ddb commit 8a599b1

File tree

1 file changed

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

1 file changed

+97
-78
lines changed

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

Lines changed: 97 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -6,128 +6,147 @@ 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 an 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 a more detailed documentation on how the to use the Cloudflare Open Next adapter visit the [Open Next 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. 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.
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 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.
4834

49-
:::
35+
Next supports Partial Prerendering to combine static and dynamic components in the same route.
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).**
42+
<PackageManagers
43+
type="create"
44+
pkg="cloudflare@latest my-next-app"
45+
args={"--framework=next --platform=workers"}
46+
/>
5847

59-
### 2. Add a Wrangler configuration file
48+
<Details header="What's happening behind the scenes?">
49+
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.
50+
</Details>
6051

61-
Then, add a [Wrangler configuration file](/workers/wrangler/configuration/) to the root directory of your Next.js app:
52+
2. **Develop locally.**
6253

63-
<WranglerConfig>
54+
After creating your project, run the following command in your project directory to start a local development server.
55+
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.
6456

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-
```
57+
<PackageManagers type="run" args="dev" />
7258

73-
</WranglerConfig>
59+
3. **Test your site with the Cloudflare adapter.**
7460

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-
:::
61+
The command used in the previous step uses the Next.js development server to offer a great developer experience.
62+
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.
7863

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/).
64+
<PackageManagers type="run" args="preview" />
8065

81-
### 3. Update `package.json`
66+
4. **Deploy your project.**
8267

83-
Add the following to the scripts field of your `package.json` file:
68+
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.
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+
<PackageManagers type="run" args="deploy" />
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+
</Steps>
9473

95-
### 4. Optionally add caching
74+
## Deploy an existing Next.js project on Workers
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+
You can convert an existing Next.js application to run on Cloudflare
9877

99-
For more details check the relevant [official Open Next documentation](https://opennext.js.org/cloudflare/caching).
78+
<Steps>
10079

101-
### 5. Develop locally
80+
1. **Install [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare)**
10281

103-
You can continue to run `next dev` when developing locally.
82+
<PackageManagers type="install" pkg="@opennextjs/cloudflare@latest" />
10483

105-
### 6. Preview locally your application and create an OpenNext config file
84+
2. **Add a Wrangler configuration file**
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+
In your project root, create a [Wrangler configuration file](/workers/wrangler/configuration/) with the following content:
10987

110-
```sh
111-
npm run preview
112-
```
88+
<WranglerConfig>
89+
```toml
90+
main = ".open-next/worker.js"
91+
name = "my-app"
92+
compatibility_date = "2025-03-25"
93+
compatibility_flags = ["nodejs_compat"]
94+
assets = { directory = ".open-next/assets", binding = "ASSETS" }
95+
```
96+
</WranglerConfig>
11397

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.
98+
:::note
99+
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.
100+
:::
116101

117-
### 7. Deploy to Cloudflare Workers
102+
3. **Add a configuration file for OpenNext**
118103

119-
Either deploy via the command line:
104+
In your project root, create an OpenNext configuration file name `open-next.config.ts` with the following content:
120105

121-
```sh
122-
npm run deploy
123-
```
106+
```ts
107+
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
124108

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.
109+
export default defineCloudflareConfig();
110+
```
126111

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

129-
## Static assets
148+
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.
130149

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.
150+
<PackageManagers type="run" args="deploy" />
132151

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

0 commit comments

Comments
 (0)