---
name: azion-get-started-with-opennext
description: >-
  Get started with OpenNext on Azion: create or adapt a Next.js app, configure caching and storage for ISR/SSG, develop locally with the Azion CLI, and deploy to production.
---

# Get Started With OpenNext

The `@aziontech/opennextjs-azion` adapter lets you deploy Next.js apps to Azion Web Platform. This guide will help you set up a new or existing Next.js project for Azion, configure caching, develop locally, and deploy to production.

---

### Prerequisites

- [CLI Installed](/en/documentation/devtools/cli/#install-the-cli).

---

#### Creating a New Next.js App

To create a new Next.js app pre-configured for Azion:

```sh
npx create-next-app@14.2.4 my-next-app --use-npm
cd my-next-app
npm install @aziontech/opennextjs-azion@latest
```

Or use a starter template:

- [Next.js + TypeScript + Tailwind Template](https://github.com/aziontech/azion-samples/tree/dev/templates/opennextjs/nextal-next-typescript-tailwind)
- [Node Playground (Next.js 13)](https://github.com/aziontech/bundler-examples/tree/main/examples/nextjs/node-playground-13)

---

#### Existing Next.js Apps

1. Install the Azion Adapter:

```sh
npm install @aziontech/opennextjs-azion@latest
```

2. Configure `open-next.config.ts`:

Create or update `open-next.config.ts` in your project root. Example:

```ts
import { defineAzionConfig } from "@aziontech/opennextjs-azion";

export default defineAzionConfig({
  // See https://www.azion.com/en/documentation/platform/applications/#cache for advanced options
});
```

3. Update `tsconfig.json`:

> **Warning**
>
> Your `tsconfig.json` must include: `json "moduleResolution": "bundler" `. This is required for correct build and runtime behavior.

If you encounter issues with ESM or `open-next.config.ts`, you may need to add:

```json
"exclude": ["node_modules", "open-next.config.ts"]
```

See [Known Issues](/en/documentation/devtools/runtime/frameworks/nextjs-compatibility/#known-issues) for more details.

1. Azion CLI Build and Deploy:

- `azion build`: Builds your app for Azion.
- `azion preview`: Runs a local preview using Azion CLI.
- `azion deploy`: Deploys to Azion Web Platform using Remote Deployment.
  - or `azion deploy --local` to deploy to Azion Web Platform using Local Deployment.

5. Set Up Caching and Storage:

Example Azion config:

```ts
AzionCache
Type definition for the cache configuration.
```

Properties:

| Property                  | Type                                               | Description                                         |
| ------------------------- | -------------------------------------------------- | --------------------------------------------------- |
| name                      | string                                             | Name of the cache configuration.                    |
| stale?                    | boolean                                            | Whether to allow stale content.                     |
| queryStringSort?          | boolean                                            | Whether to sort query string parameters.            |
| methods?                  | CacheMethods                                       | HTTP methods to cache.                              |
| post?                     | boolean                                            | Whether to cache POST requests.                     |
| options?                  | boolean                                            | Whether to cache OPTIONS requests.                  |
| browser?                  | BrowserCacheConfig                                 | Browser cache settings.                             |
| browser.maxAgeSeconds     | number \| string                                   | Maximum age for browser cache in seconds.           |
| edge?                     | EdgeCacheConfig                                    | Cache settings.                                     |
| edge.maxAgeSeconds        | number \| string                                   | Maximum age for cache in seconds.                   |
| cacheByCookie?            | CacheByCookieConfig                                | Cache by cookie settings.                           |
| cacheByCookie.option      | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Cache by cookie option.                             |
| cacheByCookie.list?       | string\[]                                          | List of cookies to use for caching.                 |
| cacheByQueryString?       | CacheByQueryStringConfig                           | Cache by query string settings.                     |
| cacheByQueryString.option | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Cache by query string option.                       |
| cacheByQueryString.list?  | string\[]                                          | List of query string parameters to use for caching. |

```js
// azion.config.cjs
module.exports = {
  build: { preset: "opennextjs", polyfills: true },
  origin: [{ name: "origin-storage-default", type: "object_storage" }],
  functions: [{ name: "handler", path: ".edge/worker.js" }],
  cache: [
    {
      name: 'Default Cache',
      browser: { maxAgeSeconds: 3600 },
      edge: { maxAgeSeconds: 7200 },
    },
  ],
  rules: {
    request: [
      {
        name: "Set storage origin for _next/static",
        match: "^/_next/static/",
        behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
      },
      {
        name: "Deliver Static Assets",
        match: ".(css|js|ttf|woff|woff2|pdf|svg|jpg|jpeg|gif|bmp|png|ico|mp4|json)$",
        behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
      },
      {
        name: "Execute Function",
        match: "^/",
        behavior: { runFunction: "handler", forwardCookies: true },
      },
    ],
  },
};
```

---

### Local Development

Use the [Azion CLI](/en/documentation/devtools/cli/) for local development:

```sh
azion dev
```

This runs your Application locally, simulating the Azion platform. [See Troubleshooting](/en/documentation/guides/application-development/frameworks/troubleshooting/) for tips on debugging and log monitoring.

---

### Deployment

Deploy your app to Azion Web Platform:

```sh
azion deploy
```

Or use the Azion CLI to deploy to Azion Web Platform using local deployment:

```sh
azion deploy --local
```

---

### Best Practices & Troubleshooting

- See [Known Issues](/en/documentation/devtools/runtime/frameworks/nextjs-compatibility/#known-issues) for important config notes.
- See [Troubleshooting](/en/documentation/guides/application-development/frameworks/troubleshooting/) for local dev, logging, and debugging tips.
- Explore [Examples](/en/documentation/devtools/runtime/frameworks/nextjs-compatibility/#starter-projects) for starter projects and templates.
- For advanced caching, see [Caching](/en/documentation/platform/applications/#cache).