Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 19 additions & 40 deletions src/content/docs/workers/frameworks/framework-guides/nextjs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,11 @@ import {
WranglerConfig
} from "~/components";

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.

:::note
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).
:::
## New apps

To create a new Next.js app, pre-configured to run on Cloudflare using [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), run:
Expand All @@ -36,7 +41,7 @@ To create a new Next.js app, pre-configured to run on Cloudflare using [`@openne

## Existing Next.js apps

:::note[Minimum required Wrangler version: 3.78.10.]
:::note[Minimum required Wrangler version: 3.99.0.]

Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).

Expand Down Expand Up @@ -77,58 +82,32 @@ You configure your Worker and define what resources it can access via [bindings]
Add the following to the scripts field of your `package.json` file:

```json
"build:worker": "opennextjs-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](https://www.npmjs.com/package/@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](/workers/wrangler/) and deploy to Cloudflare.
- `npm run dev:worker`: Takes the output generated by `build:worker` and runs it locally in [workerd](https://github.com/cloudflare/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 `dev:worker`, allowing you to quickly preview your app running locally in the Workers runtime, via a single command.
- `npm run deploy:worker`: Builds your app, and then deploys it to Cloudflare

### 4. Add caching with Workers KV

`opennextjs/cloudflare` uses [Workers KV](/kv/) as the cache for your Next.js app. Workers KV is [fast](https://blog.cloudflare.com/faster-workers-kv) and uses Cloudflare's [Tiered Cache](/cache/how-to/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

```sh
npx wrangler@latest kv namespace create NEXT_CACHE_WORKERS_KV
"preview": "opennextjs-cloudflare && wrangler dev",
"deploy": "opennextjs-cloudflare && wrangler deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
```

#### Add the KV namespace to your Worker
- `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.

<WranglerConfig>
### 4. Optionally add caching

```toml
[[kv_namespaces]]
binding = "NEXT_CACHE_WORKERS_KV"
id = "<YOUR_NAMESPACE_ID>"
```
Caching is actively being worked on. It is fully functional for development and we are working on an optimized implementation suitable for production.

</WranglerConfig>

#### 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`.
For more details check the relevant [official Open Next documentation](https://opennext.js.org/cloudflare/caching).

### 5. Develop locally

You can continue to run `next dev` when developing locally.

### 6. Preview locally your application and create an OpenNext config file

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.

To preview your application in such way run:
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.
This allows you to test changes in the same runtime that your app runs in, when deployed to Cloudflare:

```sh
npm run preview:worker
npm run preview
```

This command will build your OpenNext application, also creating, if not already present, an `open-next.configs.ts` file for you.
Expand All @@ -139,7 +118,7 @@ This is necessary if you want to deploy your application with a GibHub/GitLab in
Either deploy via the command line:

```sh
npm run deploy:worker
npm run deploy
```

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.
Expand Down
Loading