Pular para o conteúdo

Next.js

Atualizado em Ver como Markdown

Start from CLI - scaffold a Next.js project on Workers.


								
									
									npm
									 create cloudflare@latest -- my-next-app --framework=next

This is a simple getting started guide. For detailed documentation on how to use the Cloudflare OpenNext adapter, visit the OpenNext website ↗.

What is Next.js?

Next.js ↗ is a React ↗ framework for building full stack applications.

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.

You can deploy your Next.js app to Cloudflare Workers using the OpenNext adapter.

Next.js supported features

Most Next.js features are supported by the Cloudflare OpenNext adapter:

Feature Cloudflare adapter Notes
App Router 🟢 supported
Pages Router 🟢 supported
Route Handlers 🟢 supported
React Server Components 🟢 supported
Static Site Generation (SSG) 🟢 supported
Server-Side Rendering (SSR) 🟢 supported
Incremental Static Regeneration (ISR) 🟢 supported
Server Actions 🟢 supported
Response streaming 🟢 supported
asynchronous work with next/after 🟢 supported
Middleware 🟢 supported
Image optimization 🟢 supported Supported via Cloudflare Images
Partial Prerendering (PPR) 🟢 supported PPR is experimental in Next.js
Composable Caching ('use cache') 🟢 supported Composable Caching is experimental in Next.js
Node.js in Middleware ⚪ not yet supported Node.js middleware introduced in 15.2 are not yet supported

Deploy a new Next.js project on Workers

  1. Create a new project with the create-cloudflare CLI (C3).

    
								
									
									npm
									 create cloudflare@latest -- my-next-app --framework=next

    What's happening behind the scenes?

    When you run this command, C3 creates a new project directory, initiates Next.js's official setup tool ↗, and configures the project for Cloudflare. It then offers the option to instantly deploy your application to Cloudflare.

  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.

    
								
									
									npm
									 run dev

  3. Test and preview your site with the Cloudflare adapter.

    
								
									
									npm
									 run preview

    What's the difference between dev and preview?

    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 or a custom domain from your local machine or any CI/CD system (including 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.

    
								
									
									npm
									 run deploy

Deploy an existing Next.js project on Workers

Next.js Detected
Generated configuration
wrangler.jsonc
main: .open-next/worker.js
wrangler.jsonc
assets: directory: .open-next/assets
wrangler.jsonc
compatibility_flags: nodejs_compat
wrangler.jsonc
observability: enabled: true
package.json
adapter: @opennextjs/cloudflare
Workers Deployed
Wrangler handles configuration automatically

Manual configuration

If you prefer to configure your project manually, follow the steps below.

  1. Install @opennextjs/cloudflare ↗

    
								
									
									npm
									 i @opennextjs/cloudflare@latest

  2. Install wrangler CLI ↗ as a devDependency

    
								
									
									npm
									 i -D wrangler@latest

  3. Add a Wrangler configuration file

    In your project root, create a Wrangler configuration file with the following content:

    {
	"$schema": "./node_modules/wrangler/config-schema.json",
	"main": ".open-next/worker.js",
	"name": "my-app",
	// Set this to today's date
	"compatibility_date": "2026-07-20",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"assets": {
		"directory": ".open-next/assets",
		"binding": "ASSETS"
	}
}
    "$schema" = "./node_modules/wrangler/config-schema.json"
main = ".open-next/worker.js"
name = "my-app"
# Set this to today's date
compatibility_date = "2026-07-20"
compatibility_flags = [ "nodejs_compat" ]

[assets]
directory = ".open-next/assets"
binding = "ASSETS"

  4. Add a configuration file for OpenNext

    In your project root, create an OpenNext configuration file named open-next.config.ts with the following content:

    import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig();

  5. Update package.json

    You can add the following scripts to your package.json:

    "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"

    Usage
    • 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.

  6. 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.

    
								
									
									npm
									 run dev

  7. 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 works correctly in this environment.

    
								
									
									npm
									 run preview

  8. Deploy your project.

    You can deploy your project to a *.workers.dev subdomain or a custom domain from your local machine or any CI/CD system (including 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.

    
								
									
									npm
									 run deploy