Next.js

New apps

To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare ↗, run:

npm create cloudflare@latest --no-auto-update --experimental --framework next

Existing Next.js apps

::: note Minimum required Wrangler version: 3.78.10. Check your version by running wrangler version. To update Wrangler, refer to Install/Update Wrangler. :::

1. Install @opennextjs/cloudflare

First, install @opennextjs/cloudflare ↗:

npm install --save-dev @opennextjs/cloudflare

2. Add a wrangler.toml file

Then, add a wrangler.toml file to the root directory of your Next.js app:

main = ".worker-next/index.mjs"
name = "my-app"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
experimental_assets = { directory = ".worker-next/assets", binding = "ASSETS" }

Note

As shown above, you must enable the nodejs_compat compatibility flag and set your compatibility date to 2024-09-23 or later for your Next.js app to work with @opennextjs/cloudflare.

wrangler.toml is where you configure your Worker and define what resources it can access via bindings.

3. Update package.json

Add the following to the scripts field of your package.json file:

"build:worker": "cloudflare",
"dev:worker": "wrangler dev --port 8771",
"preview:worker": "npm run build:worker && npm run dev:worker",
"deploy:worker": "npm run build:worker && wrangler deploy"

• npm run build:worker: Runs the @opennextjs/cloudflare ↗ adapter. This first builds your app by running next build behind the scenes, and then transforms the build output to a format that you can run locally using Wrangler and deploy to Cloudflare.
• npm run dev:worker: Takes the output generated by build:worker and runs it locally in workerd ↗, the open-source Workers Runtime, allowing you to run the app locally in the same environment that it will run in production. If you instead run next dev, your app will run in Node.js, which is a different JavaScript runtime from the Workers runtime, with differences in behavior and APIs.
• npm run preview:worker: Runs build:worker and then preview:worker, allowing you to quickly preview your app running locally in the Workers runtime, via a single command.
• npm run deploy: Builds your app, and then deploys it to Cloudflare

4. Add caching with Workers KV

opennextjs/cloudflare uses Workers KV as the cache for your Next.js app. Workers KV is fast ↗ and uses Cloudflare’s Tiered Cache to increase cache hit rates. When you write cached data to Workers KV, you write to storage that can be read by any Cloudflare location. This means your app can fetch data, cache it in KV, and then be read by subsequent requests from this cache anywhere in the world.

To enable caching, you must:

Create a KV namespace

npx wrangler@latest kv namespace create NEXT_CACHE_WORKERS_KV

Add the KV namespace to your Worker

[[kv_namespaces]]
binding = "NEXT_CACHE_WORKERS_KV"
id = "<YOUR_NAMESPACE_ID>"

Set the name of the binding to NEXT_CACHE_WORKERS_KV

As shown above, the name of the binding that you configure for the KV namespace must be set to NEXT_CACHE_WORKERS_KV.

5. Develop locally

You can continue to run next dev when developing locally.

In step 3, we also added the npm run preview:worker, which allows you to quickly preview your app running locally in the Workers runtime, rather than in Node.js. This allows you to test changes in the same runtime that your app runs in, when deployed to Cloudflare.

6. Deploy to Cloudflare Workers

Either deploy via the command line:

npm run deploy

Or connect a GitHub or GitLab repository, and Cloudflare will automatically build and deploy each pull request you merge to your production branch.

---

Static assets

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.

When using Workers Assets, Cloudflare will first attempt to serve any static assets which match the incoming request.

For example, if you have requests for /logo.png and /blog/hello-world.html in your assets directory, and make requests for /logo.png and /blog/hello-world, those files will be served respectively. The html_handling option allows you to customize the serving of HTML files if you have specific needs around redirects and trailing slashes.

If a request does not match a static asset, Cloudflare will then invoke your Worker script module, if one is present. This can be configured with the main property in wrangler.toml.

Finally, if a request does not match any static assets, and either a Worker script module is not present, or from within that Worker script module, the asset binding’s fetch method is called (e.g. env.ASSETS.fetch(request)), Cloudflare will fall back to evaluating the not_found_handling behavior. By default, it will serve a null-body 404-status response, but this can be configured to instead serve custom HTML 404 pages, or to serve a single-page application (SPA).

At present, there is no way to customize this routing behavior beyond the html_handling and not_found_handling options. We plan to offer additional configuration controls, such as allowing you to always run the Worker script modules for certain paths, in the future.