# Azion and Next.js compatibility

Compatibility between different versions of Next.js and Azion Web Platform.

:::note
You can find more detailed examples in the [Azion Bundler repository](https://github.com/aziontech/bundler/).
:::

---

## OpenNext

The [`@aziontech/opennextjs-azion`](https://www.npmjs.com/package/@aziontech/opennextjs-azion) adapter lets you deploy Next.js apps to [Azion Functions](https://www.azion.com/en/products/edge-functions/) using the [Node.js "runtime" from Next.js](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).

### Get Started

##### New apps

To create a new Next.js app, pre-configured to run on Azion using `@aziontech/opennextjs-azion`, run:

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

##### Existing Next.js apps

[Follow the guide here](/en/documentation/products/guides/opennext/get-started/) to use [@aziontech/opennextjs-azion](https://www.npmjs.com/package/@aziontech/opennextjs-azion) with an existing Next.js app.

### Supported Next.js versions

All minor and patch versions of Next.js 15 and the latest minor of Next.js 14 are supported.

To help improve compatibility, we encourage you to [report bugs](https://github.com/aziontech/opennextjs-azion/issues) and contribute code!

### Supported Next.js features

| Feature | Support | Comments |
|---|---|---|
| [App Router](https://nextjs.org/docs/app) | 🟢 | |
| [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) | 🟢 | |
| [Dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) | 🟢 | |
| [Static Site Generation (SSG)](https://nextjs.org/docs/app/building-your-application/rendering/server-components#static-rendering-default) | 🟢 | |
| [Server-Side Rendering (SSR)](https://nextjs.org/docs/app/building-your-application/rendering/server-components) | 🟢 | |
| [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) | 🟢 | |
| [Node Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware#runtime) | 🟡 | introduced in 15.2 are not yet supported |
| [Image Optimization](https://nextjs.org/docs/app/building-your-application/optimizing/images) | 🔴 | |
| [Partial Prerendering (PPR)](https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering) | 🟢 | |
| [Pages Router](https://nextjs.org/docs/pages) | 🟢 | |
| [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) | 🟢 | |
| [Support for after](https://nextjs.org/blog/next-15-rc#executing-code-after-a-response-with-nextafter-experimental) | 🟢 | |
| [Composable Caching](https://nextjs.org/blog/composable-caching) | 🔴 | ('use cache') |

:::note
Azion Functions have a maximum size limit of 50 MB per function. After building your project, pay attention to the compressed (gzipped) size of your deployment package—only the compressed size counts toward this limit.
For more details, see the [documentation on Function size limits](/en/documentation/products/build/applications/functions/#limits).
:::

### Examples

To create a new Next.js app for Azion, you can use the following starter projects and templates:

#### Basic starter projects

- [Next.js + TypeScript + Tailwind Template](https://github.com/aziontech/azion-samples/tree/dev/templates/opennextjs/nextal-next-typescript-tailwind) — a ready-to-use template for building modern Next.js apps on Azion Functions.
- [Node Playground (Next.js 13)](https://github.com/aziontech/bundler-examples/tree/main/examples/nextjs/node-playground-13) — an example showing how to run Next.js 13 in a Node.js environment on Azion.

You can use these repositories to understand how to configure your Next.js app to run on Azion, or as a starting point for your own projects.

### Known issues

#### TS Config
- Your `tsconfig.json` must include the following setting:
  
```json
"moduleResolution": "bundler"
```
  
 If this is not set, you may encounter issues during the build or runtime process.

- There is a known issue with ESM and the `open-next.config.ts` file. If you have an older project or one that depends on a specific TypeScript version or custom configuration, you may need to:
  - Reconfigure your project (for example, by setting `moduleResolution: bundler` as above), **or**
  - Add the following to your `tsconfig.json`:

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

Whether this works depends on your project setup. In some cases, excluding `open-next.config.ts` allows the build to proceed, but you may still encounter errors, especially if your project uses features like `_app.mdx` or other advanced configurations. This is particularly relevant for projects that haven't been tested with these setups, and issues may also occur in other environments (such as the Cloudflare package).

#### Local Development

- Some applications may use Node.js or Web Standard APIs that are not fully supported by Azion's local development environment. However, these features might be available in the actual Azion runtime.

:::tip
If your application does not work as expected during local development, try deploying it to Azion before troubleshooting further, as it may work correctly in the deployed environment.
:::

## Next.js 14.x.y

| Feature | Support | Comments |
|---|---|---|
| Static Pages | 🟢 | |
| SSG | 🟢 | |

---

## Azion Runtime 

### Versions: 12.2.x, 12.3.x

| Pages Router Support | Support | Comments |
|---|---|---|
| Static Pages | 🟢 | |
| SSR | 🟢 | |
| SSG | 🟢 | |
| API Routes | 🟢 | |
| Dynamic Routes | 🟢 | |
| Middleware  | 🟡 | Features: rewrite, redirect, continue to response, set request header, throw error, set response header, and set response cookie|
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition  |
| i18n routing | 🟢 | |

### Versions: 13.0.x, 13.1.x, 13.2.x, 13.3.x, 13.4.x, 13.5.x

| Pages Router Support | Support | Comments |
|---|---|---|
| Static Pages | 🟢 | 
| SSR | 🟢 | | 
| SSG | 🟢 | | 
| API Routes | 🟢 | | 
| Dynamic Routes | 🟢 | |
| Middleware | 🟡 | Features: rewrite, redirect, continue to response, set request header, throw error, return response, set response header, and set response cookie | 
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition | 
| i18n routing | 🟢 | | 
| Custom errors | 🟢 | | 

<br />

| App Router Support | Support | Comments |
|---|---|--- | 
| App router | 🟢 | Basic structure, routing, and layouts| 
| Server Components | 🟢 | | 
| Route Handlers | 🟢 | | 
| Dynamic Routes | 🟢 | |
| Middleware  | 🟡 | Features: rewrite, redirect, continue to response, set request header, throw error, set response header, and set response cookie|
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition  |
| i18n routing | 🟢 | |
| Custom errors | 🟢 | | 

---

## Node Runtime 

### Versions: 12.3.x

| Pages Router Support | Support | Comments |
|---|---|---| 
| Static Pages | 🟢 | | 
| SSR | 🟢 | | 
| SSG | 🟢 | | 
| API Routes | 🟢 | | 
| Dynamic Routes | 🟢 | |
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition | 
| i18n routing | 🟢 | | 
| Custom errors | 🟢 | | 

---

## About Next.js

**Next.js** is a flexible **React** framework that helps you to build fast and modern applications. It can be used to solve some application requirements such as:

- Routing
- Data Fetching
- Integrations

Next.js allows you to use static generation on a per-page basis, through **Incremental Static Regeneration (ISR)**, without having to rebuild the entire application. That means you can enjoy the benefits of static and still be able to scale.

A **page**, in Next.js, is a **React Component** inside a file. This file can be in any of the following extensions:

- `.js`
- `.jsx`
- `.ts`
- `.tsx`

Every page has an associated *route* based on its file name.

**Example**:

Let's say you create `pages/azion.js` exporting a React component.

```js
  export default function Azion() {
    return <div>The easiest way to build, deploy, observe and secure modern applications.</div>
  }
```

The page will be accessible at `/azion`:

```js
pages/
    azion.js
```

---

## Pre-rendering

Next.js generates HTML for each page in advance, relieving client-side Javascript of this burden. As a consequence, this pre-rendering can help your application have better performance and Search Engine Optimization (SEO).

### Pre-rendering forms

- Static Generation: during build time, the HTML is generated and reused on each request.
- Server-side Rendering: the HTML is generated on each request.


To dive deeper into the Next.js world, read the [Next.js documentation](https://nextjs.org/docs/getting-started)

---