npmcreatecloudflare@latest--my-next-app--framework=next

yarncreatecloudflaremy-next-app--framework=next

pnpmcreatecloudflare@latestmy-next-app--framework=next

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

Next.js ↗ is aReact ↗ 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.

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

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

   • npm
   • yarn
   • pnpm

   npmcreatecloudflare@latest--my-next-app--framework=next

   What's happening behind the scenes?

   When you run this command, C3 creates a new project directory, initiatesNext.js's official setuptool ↗, andconfigures the project for Cloudflare. It then offers the option toinstantly 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
   • yarn
   • pnpm

   npmrundev

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

   • npm
   • yarn
   • pnpm

   npmrunpreview

   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 onCloudflare Workers, which uses theworkerd runtime. Therefore whenrunning integration tests and previewing your application, you should usethe preview command, which is more accurate to production, as it executesyour application in theworkerd runtime usingwrangler dev.

4. Deploy your project.

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

   npmrundeploy

   Note

   Workers Builds requires you to configure environment variables in the"Build Variables and secrets" section.

   This ensures the Next build has the necessary access to both publicNEXT_PUBLC... variables andnon-NEXT_PUBLIC_... ↗, which are essential for tasks like inlining and building SSG pages.

   Learn more in theOpenNext environment variable guide ↗

You can convert an existing Next.js application to run on Cloudflare

1. Install@opennextjs/cloudflare ↗

   • npm
   • yarn
   • pnpm

   npmi@opennextjs/cloudflare@latest

2. Installwrangler CLI ↗ as a devDependency

   • npm
   • yarn
   • pnpm

   npmi-Dwrangler@latest

3. Add a Wrangler configuration file

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

   • wrangler.jsonc
   • wrangler.toml

   {
   "$schema":"./node_modules/wrangler/config-schema.json",
   "main":".open-next/worker.js",
   "name":"my-app",
   "compatibility_date":"2025-12-18",
   "compatibility_flags":[
   "nodejs_compat"
   ],
   "assets":{
   "directory":".open-next/assets",
   "binding":"ASSETS"
   }
   }

   Note

   As shown above, you must enable thenodejs_compat compatibility flagand set yourcompatibility date to2024-09-23 or later for your Next.js app to work with @opennextjs/cloudflare.

4. Add a configuration file for OpenNext

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

   import{defineCloudflareConfig} from"@opennextjs/cloudflare";
   exportdefaultdefineCloudflareConfig();

   Note

   open-next.config.ts is where you can configure the caching, see theadapter documentation ↗ for more information

5. Updatepackage.json

   You can add the following scripts to yourpackage.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 toquickly preview your app running locally in the Workers runtime, via asingle command.
   • deploy: Builds your app, and then deploys it toCloudflare
   • cf-typegen: Generates acloudflare-env.d.ts file at theroot 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
   • yarn
   • pnpm

   npmrundev

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
   • yarn
   • pnpm

   npmrunpreview

8. Deploy your project.

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

   npmrundeploy

   Note

   Workers Builds requires you to configure environment variables in the"Build Variables and secrets" section.

   This ensures the Next build has the necessary access to both publicNEXT_PUBLC... variables andnon-NEXT_PUBLIC_... ↗, which are essential for tasks like inlining and building SSG pages.

   Learn more in theOpenNext environment variable guide ↗