-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add Next.js to supported Workers frameworks (#17124)
* Add Next.js to supported Workers frameworks refs opennextjs/docs#3 It is intentional that this guide is not the same as other guides here. Need to explain how to take an _existing_ Next.js app and deploy it to Cloudflare, as we do here: https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/get-started/ * Update src/content/docs/workers/frameworks/framework-guides/nextjs.mdx Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Tanushree <[email protected]> * Apply suggestions from code review * Apply suggestions from code review Co-authored-by: ToriLindsay <[email protected]> --------- Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com> Co-authored-by: Tanushree <[email protected]> Co-authored-by: ToriLindsay <[email protected]>
- Loading branch information
1 parent
6fa6835
commit b098954
Showing
1 changed file
with
118 additions
and
0 deletions.
There are no files selected for viewing
118 changes: 118 additions & 0 deletions
118
src/content/docs/workers/frameworks/framework-guides/nextjs.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,118 @@ | ||
--- | ||
pcx_content_type: how-to | ||
title: Next.js | ||
head: [] | ||
description: Create an Next.js application and deploy it to Cloudflare Workers with Workers Assets. | ||
--- | ||
|
||
import { | ||
Badge, | ||
Description, | ||
InlineBadge, | ||
Render, | ||
PackageManagers, | ||
} from "~/components"; | ||
|
||
#### New apps | ||
|
||
To create a new Next.js app, pre-configured to run on Cloudflare using [`@opennextjs/cloudflare`](https://opennext.js.org/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](/workers/wrangler/install-and-update/). | ||
::: | ||
|
||
##### 1. Install @opennextjs/cloudflare | ||
|
||
First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare): | ||
|
||
```sh | ||
npm install --save-dev @opennextjs/cloudflare | ||
``` | ||
|
||
##### 2. Add a `wrangler.toml` file | ||
|
||
Then, add a [`wrangler.toml`](/workers/wrangler/configuration/) file to the root directory of your Next.js app: | ||
|
||
```toml | ||
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](/workers/runtime-apis/nodejs/) *and* set your [compatibility date](/workers/configuration/compatibility-dates/) 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](/workers/runtime-apis/bindings/). | ||
|
||
##### 3. Update `package.json` | ||
|
||
Add the following to the scripts field of your `package.json` file: | ||
|
||
```json | ||
"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](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 `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](/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 | ||
|
||
``` | ||
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: | ||
|
||
```sh | ||
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. | ||
|
||
--- | ||
|
||
## 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. | ||
|
||
<Render file="workers-assets-routing-summary" /> |