Get Started
New apps
To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run:
npx https://prerelease-registry.devprod.cloudflare.dev/workers-sdk/runs/11040899018/npm-package-create-cloudflare-6830 --no-auto-update --experimental --framework next
Existing Next.js apps
1. Install @opennextjs/cloudflare
First, install @opennextjs/cloudflare (opens in a new tab):
npm install --save-dev @opennextjs/cloudflare
2. Install Wrangler, and add a wrangler.toml
file
Install the Wrangler CLI (opens in a new tab) as a devDependency:
npm install -D wrangler@latest
You must use Wrangler version 3.78.10
or later to deploy Next.js apps using @opennextjs/cloudflare
.
Then, add a wrangler.toml
(opens in a new tab) 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" }
As shown above, you must enable the nodejs_compat
compatibility flag (opens in a new tab) and set your compatibility date (opens in a new tab) to 2024-09-23
or later, in order 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 (opens in a new tab) adapter. This first builds your app by runningnext build
behind the scenes, and then transforms the build output to a format that you can run locally using Wrangler (opens in a new tab), and deploy to Cloudflare.npm run dev:worker
: Takes the output generated bybuild:worker
and runs it locally in workerd (opens in a new tab), 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 runnext 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
: Runsbuild:worker
and thenpreview: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 (opens in a new tab) as the cache for your Next.js app. Workers KV is fast (opens in a new tab) and uses Cloudflare's Tiered Cache (opens in a new tab) 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 subsequent requests anywhere around the world can read from this cache.
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 as your app will run 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 (opens in a new tab), and Cloudflare will automatically build and deploy each pull request you merge to your production branch.