Skip to content

Commit ea4df1d

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

File tree

1 file changed

+96
-69
lines changed
  • src/content/docs/workers/frameworks/framework-guides

1 file changed

+96
-69
lines changed

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

Lines changed: 96 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,12 @@ 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

1817
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.
@@ -31,103 +30,131 @@ To create a new Next.js app, pre-configured to run on Cloudflare using [`@openne
3130
args={"--framework=next --platform=workers"}
3231
/>
3332

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

43-
## Existing Next.js apps
37+
## What is Next.js
4438

45-
:::note[Minimum required Wrangler version: 3.99.0.]
39+
[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.
4640

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

49-
:::
43+
Next supports Partial Prerendering to combine static and dynamic components in the same route.
5044

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

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

55-
```sh
56-
npm install --save-dev @opennextjs/cloudflare
57-
```
49+
1. **Create a new project with the create-cloudflare CLI (C3).**
50+
<PackageManagers
51+
type="create"
52+
pkg="cloudflare@latest my-next-app"
53+
args={"--framework=next --platform=workers"}
54+
/>
5855

59-
### 2. Add a Wrangler configuration file
56+
<Details header="What's happening behind the scenes?">
57+
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.
58+
</Details>
6059

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

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

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

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

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

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

81-
### 3. Update `package.json`
74+
4. **Deploy your project.**
8275

83-
Add the following to the scripts field of your `package.json` file:
76+
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.
8477

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-
```
78+
<PackageManagers type="run" args="deploy" />
9079

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.
80+
</Steps>
9481

95-
### 4. Optionally add caching
82+
## Deploy an existing Next.js project on Workers
9683

97-
Caching is actively being worked on. It is fully functional for development and we are working on an optimized implementation suitable for production.
84+
You can convert an existing Next.js application to run on Cloudflare
9885

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

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

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

105-
### 6. Preview locally your application and create an OpenNext config file
92+
2. **Add a Wrangler configuration file**
10693

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:
94+
In your project root, create a [Wrangler configuration file](/workers/wrangler/configuration/) with the following content:
10995

110-
```sh
111-
npm run preview
112-
```
96+
<WranglerConfig>
97+
```toml
98+
main = ".open-next/worker.js"
99+
name = "my-app"
100+
compatibility_date = "2025-03-25"
101+
compatibility_flags = ["nodejs_compat"]
102+
assets = { directory = ".open-next/assets", binding = "ASSETS" }
103+
```
104+
</WranglerConfig>
113105

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.
106+
:::note
107+
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.
108+
:::
116109

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

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

121-
```sh
122-
npm run deploy
123-
```
114+
```ts
115+
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
124116

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.
117+
export default defineCloudflareConfig();
118+
```
126119

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

129-
## Static assets
156+
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.
130157

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

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

0 commit comments

Comments
 (0)