# 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/products/azion-cli/overview/#installing-azion-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/products/build/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/azion-edge-runtime/compatibility/nextjs/#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/products/azion-cli/overview/) for local development:

```sh
azion dev
```

This runs your Application locally, simulating the Azion platform. [See Troubleshooting](/en/documentation/products/guides/opennext/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/azion-edge-runtime/compatibility/nextjs/#known-issues) for important config notes.
- See [Troubleshooting](/en/documentation/products/guides/opennext/troubleshooting/) for local dev, logging, and debugging tips.
- Explore [Examples](/en/documentation/devtools/azion-edge-runtime/compatibility/nextjs/#examples) for starter projects and templates.
- For advanced caching, see [Caching](/en/documentation/products/build/applications/cache/).