In this guide, you will create a new [Next.js](https://nextjs.org/) application and deploy to Cloudflare Workers (with the new [Beta Workers Assets](https://developers.cloudflare.com/workers/static-assets/)) using the [`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare) package.

Note

If your Next.js app currently runs on Vercel, you can easily migrate your Next.js app to Cloudflare by using [Diverce](https://github.com/ygwyg/diverce), which will automatically add OpenNext to your project and create a pull request that makes it deployable to 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:

* npm

  ```sh
  npm create cloudflare@latest my-next-app -- --framework=next --platform=workers
  ```

* pnpm

  ```sh
  pnpm create cloudflare@latest my-next-app --framework=next --platform=workers
  ```

* yarn

  ```sh
  yarn create cloudflare my-next-app --framework=next --platform=workers
  ```

For setup, select the following options:

* For *What would you like to start with?*, choose `Framework Starter`.
* For *Which development framework do you want to use?*, choose `Next.js`.
* Complete the framework's own CLI wizard.
* For *Do you want to use git for version control?*, choose `Yes`.
* For *Do you want to deploy your application?*, choose `No` (we will be making some changes before deploying).

## Existing Next.js apps

Minimum required Wrangler version: 3.99.0.

Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](https://developers.cloudflare.com/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 configuration file

Then, add a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) to the root directory of your Next.js app:

* wrangler.jsonc

  ```jsonc
  {
    "main": ".open-next/worker.js",
    "name": "my-app",
    "compatibility_date": "2024-09-23",
    "compatibility_flags": [
      "nodejs_compat"
    ],
    "assets": {
      "directory": ".open-next/assets",
      "binding": "ASSETS"
    }
  }
  ```

* wrangler.toml

  ```toml
  main = ".open-next/worker.js"
  name = "my-app"
  compatibility_date = "2024-09-23"
  compatibility_flags = ["nodejs_compat"]
  assets = { directory = ".open-next/assets", binding = "ASSETS" }
  ```

Note

As shown above, you must enable the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) *and* set your [compatibility date](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) to `2024-09-23` or later for your Next.js app to work with @opennextjs/cloudflare.

You configure your Worker and define what resources it can access via [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) in the [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).

### 3. Update `package.json`

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

```json
"preview": "opennextjs-cloudflare && wrangler dev",
"deploy": "opennextjs-cloudflare && wrangler deploy",
"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts"
```

* `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.

### 4. Optionally add caching

Caching is actively being worked on. It is fully functional for development and we are working on an optimized implementation suitable for production.

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` 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
```

This command will build your OpenNext application, also creating, if not already present, an `open-next.configs.ts` file for you. This is necessary if you want to deploy your application with a GibHub/GitLab integration as presented in the next step.

### 7. Deploy to Cloudflare Workers

Either deploy via the command line:

```sh
npm run deploy
```

Or [connect a GitHub or GitLab repository](https://developers.cloudflare.com/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.

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`](https://developers.cloudflare.com/workers/static-assets/routing/#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`](https://developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys) property in the [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/).

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](https://developers.cloudflare.com/workers/static-assets/binding/)'s `fetch` method is called (e.g. `env.ASSETS.fetch(request)`), Cloudflare will fall back to evaluating the [`not_found_handling`](https://developers.cloudflare.com/workers/static-assets/routing/#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.
