Skip to content

Commit 5034f43

Browse files
LuizaVSantosLuizaVSantos
committed
feat: added open next docs
1 parent 9002e2b commit 5034f43

File tree

6 files changed

+870
-4
lines changed

6 files changed

+870
-4
lines changed

‎src/content/docs/en/pages/devtools/azion-edge-runtime/nextjs/2023-02-14-index.mdx‎

Lines changed: 89 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,93 @@ You can find more detailed examples in the [Azion Bundler repository](https://gi
1919

2020
---
2121

22+
## OpenNext
23+
24+
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).
25+
26+
### Get Started
27+
28+
##### New apps
29+
30+
To create a new Next.js app, pre-configured to run on Azion using `@aziontech/opennextjs-azion`, run:
31+
32+
```shell
33+
npx create-next-app@14.2.4 my-next-app --use-npm && cd my-next-app && npm install @aziontech/opennextjs-azion@latest
34+
```
35+
36+
##### Existing Next.js apps
37+
38+
Follow the guide [here](/azion/get-started) to use [@aziontech/opennextjs-azion](https://www.npmjs.com/package/@aziontech/opennextjs-azion) with an existing Next.js app.
39+
40+
### Supported Next.js versions
41+
42+
All minor and patch versions of Next.js 15 and the latest minor of Next.js 14 are supported.
43+
44+
To help improve compatibility, we encourage you to [report bugs](https://github.com/aziontech/opennextjs-azion/issues) and contribute code!
45+
46+
### Supported Next.js features
47+
48+
| Feature | Support | Comments |
49+
|---|---|---|
50+
| [App Router](https://nextjs.org/docs/app) | 🟢 | |
51+
| [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) | 🟢 | |
52+
| [Dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) | 🟢 | |
53+
| [Static Site Generation (SSG)](https://nextjs.org/docs/app/building-your-application/rendering/server-components#static-rendering-default) | 🟢 | |
54+
| [Server-Side Rendering (SSR)](https://nextjs.org/docs/app/building-your-application/rendering/server-components) | 🟢 | |
55+
| [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) | 🟢 | |
56+
| [Node Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware#runtime) | 🟡 | introduced in 15.2 are not yet supported |
57+
| [Image optimization](https://nextjs.org/docs/app/building-your-application/optimizing/images) | 🔴 | |
58+
| [Partial Prerendering (PPR)](https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering) | 🟢 | |
59+
| [Pages Router](https://nextjs.org/docs/pages) | 🟢 | |
60+
| [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) | 🟢 | |
61+
| [Support for after](https://nextjs.org/blog/next-15-rc#executing-code-after-a-response-with-nextafter-experimental) | 🟢 | |
62+
| [Composable Caching](https://nextjs.org/blog/composable-caching) | 🔴 | ('use cache') |
63+
64+
:::note
65+
Azion Functions have a maximum size limit of 50 MiB 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.
66+
For more details, see the [documentation on Function size limits](/en/documentation/products/build/edge-application/edge-functions/#limits).
67+
:::
68+
69+
### Examples
70+
71+
To create a new Next.js app for Azion, you can use the following starter projects and templates:
72+
73+
#### Basic starter projects
74+
75+
- [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.
76+
- [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.
77+
78+
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.
79+
80+
### Known issues
81+
82+
#### TS Config
83+
- Your `tsconfig.json` must include the following setting:
84+
85+
```json
86+
"moduleResolution": "bundler"
87+
```
88+
89+
If this is not set, you may encounter issues during the build or runtime process.
90+
91+
- 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:
92+
- Reconfigure your project (for example, by setting `moduleResolution: bundler` as above), **or**
93+
- Add the following to your `tsconfig.json`:
94+
95+
```json
96+
"exclude": ["node_modules", "open-next.config.ts"]
97+
```
98+
99+
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).
100+
101+
#### Local Development
102+
103+
- 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.
104+
105+
:::tip
106+
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.
107+
:::
108+
22109
## Next.js 14.x.y
23110

24111
| Feature | Support | Comments |
@@ -37,7 +124,7 @@ You can find more detailed examples in the [Azion Bundler repository](https://gi
37124
| Static Pages | 🟢 | |
38125
| SSR | 🟢 | |
39126
| SSG | 🟢 | |
40-
| Edge API Routes | 🟢 | |
127+
| API Routes | 🟢 | |
41128
| Dynamic Routes | 🟢 | |
42129
| Middleware | 🟡 | Features: rewrite, redirect, continue to response, set request header, throw error, set response header, and set response cookie|
43130
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition |
@@ -50,7 +137,7 @@ You can find more detailed examples in the [Azion Bundler repository](https://gi
50137
| Static Pages | 🟢 |
51138
| SSR | 🟢 | |
52139
| SSG | 🟢 | |
53-
| Edge API Routes | 🟢 | |
140+
| API Routes | 🟢 | |
54141
| Dynamic Routes | 🟢 | |
55142
| Middleware | 🟡 | Features: rewrite, redirect, continue to response, set request header, throw error, return response, set response header, and set response cookie |
56143
| Next configs | 🟡 | Features: rewrite before files, rewrite after files, rewrite fallback, redirects, and header definition |

‎src/content/docs/en/pages/guides/open-next/get-started-opennext.mdx‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
---
2+
title: Get Started With OpenNext
3+
description: >-
4+
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.
5+
permalink: /documentation/products/guides/opennext/get-started/
6+
meta_tags: >-
7+
Next.js compatibility, Azion Web Platform, SSR, SSG, Middleware Features,
8+
Static Generation, Server-side Rendering, Next.js Routing, Next.js
9+
Performance, Next.js Integrations
10+
namespace: documentation_guides_opennext_get_started
11+
---
12+
13+
14+
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.
15+
16+
---
17+
18+
### Prerequisites
19+
20+
- [CLI Installed](/en/documentation/products/azion-cli/overview/#installing-azion-cli).
21+
22+
---
23+
24+
#### Creating a New Next.js App
25+
26+
To create a new Next.js app pre-configured for Azion:
27+
28+
```sh
29+
npx create-next-app@14.2.4 my-next-app --use-npm
30+
cd my-next-app
31+
npm install @aziontech/opennextjs-azion@latest
32+
```
33+
34+
Or use a starter template:
35+
36+
- [Next.js + TypeScript + Tailwind Template](https://github.com/aziontech/azion-samples/tree/dev/templates/opennextjs/nextal-next-typescript-tailwind)
37+
- [Node Playground (Next.js 13)](https://github.com/aziontech/bundler-examples/tree/main/examples/nextjs/node-playground-13)
38+
39+
---
40+
41+
#### Existing Next.js Apps
42+
43+
1. Install the Azion Adapter:
44+
45+
```sh
46+
npm install @aziontech/opennextjs-azion@latest
47+
```
48+
49+
2. Configure `open-next.config.ts`:
50+
51+
Create or update `open-next.config.ts` in your project root. Example:
52+
53+
```ts
54+
import { defineAzionConfig } from "@aziontech/opennextjs-azion";
55+
56+
export default defineAzionConfig({
57+
// See /azion/caching for advanced options
58+
});
59+
```
60+
61+
3. Update `tsconfig.json`:
62+
63+
:::warning
64+
Your `tsconfig.json` must include: ```json "moduleResolution": "bundler" ``` This is required for correct build and runtime behavior.
65+
:::
66+
67+
If you encounter issues with ESM or `open-next.config.ts`, you may need to add:
68+
69+
```json
70+
"exclude": ["node_modules", "open-next.config.ts"]
71+
```
72+
73+
See [Known Issues](/en/documentation/devtools/azion-edge-runtime/compatibility/nextjs/#known-issues) for more details.
74+
75+
1. Azion CLI Build and Deploy:
76+
77+
- `azion build`: Builds your app for Azion.
78+
- `azion preview`: Runs a local preview using Azion CLI.
79+
- `azion deploy`: Deploys to Azion Web Platform using Remote Deployment.
80+
- or `azion deploy --local` to deploy to Azion Web Platform using Local Deployment.
81+
82+
5. Set Up Caching and Storage:
83+
84+
See the [Caching Guide](/azion/caching) for how to configure Azion Object Storage and Cache for ISR/SSG. Example Azion config:
85+
86+
```ts
87+
AzionCache
88+
Type definition for the cache configuration.
89+
```
90+
91+
Properties:
92+
93+
| Property | Type | Description |
94+
| --- | --- | --- |
95+
| name | string | Name of the cache configuration. |
96+
| stale? | boolean | Whether to allow stale content. |
97+
| queryStringSort? | boolean | Whether to sort query string parameters. |
98+
| methods? | CacheMethods | HTTP methods to cache. |
99+
| post? | boolean | Whether to cache POST requests. |
100+
| options? | boolean | Whether to cache OPTIONS requests. |
101+
| browser? | BrowserCacheConfig | Browser cache settings. |
102+
| browser.maxAgeSeconds | number \| string | Maximum age for browser cache in seconds. |
103+
| edge? | EdgeCacheConfig | Cache settings. |
104+
| edge.maxAgeSeconds | number \| string | Maximum age for cache in seconds. |
105+
| cacheByCookie? | CacheByCookieConfig | Cache by cookie settings. |
106+
| cacheByCookie.option | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Cache by cookie option. |
107+
| cacheByCookie.list? | string[] | List of cookies to use for caching. |
108+
| cacheByQueryString? | CacheByQueryStringConfig | Cache by query string settings. |
109+
| cacheByQueryString.option | 'ignore' \| 'varies' \| 'whitelist' \| 'blacklist' | Cache by query string option. |
110+
| cacheByQueryString.list? | string[] | List of query string parameters to use for caching. |
111+
112+
113+
```js
114+
// azion.config.cjs
115+
module.exports = {
116+
build: { preset: "opennextjs", polyfills: true },
117+
origin: [{ name: "origin-storage-default", type: "object_storage" }],
118+
functions: [{ name: "handler", path: ".edge/worker.js" }],
119+
cache: [
120+
{
121+
name: 'Default Cache',
122+
browser: { maxAgeSeconds: 3600 },
123+
edge: { maxAgeSeconds: 7200 },
124+
},
125+
],
126+
rules: {
127+
request: [
128+
{
129+
name: "Set storage origin for _next/static",
130+
match: "^/_next/static/",
131+
behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
132+
},
133+
{
134+
name: "Deliver Static Assets",
135+
match: ".(css|js|ttf|woff|woff2|pdf|svg|jpg|jpeg|gif|bmp|png|ico|mp4|json)$",
136+
behavior: { setOrigin: { name: "origin-storage-default", type: "object_storage" }, deliver: true },
137+
},
138+
{
139+
name: "Execute Function",
140+
match: "^/",
141+
behavior: { runFunction: "handler", forwardCookies: true },
142+
},
143+
],
144+
},
145+
};
146+
```
147+
148+
---
149+
150+
### Local Development
151+
152+
Use the [Azion CLI](/en/documentation/products/cli/) for local development:
153+
154+
```sh
155+
azion dev
156+
```
157+
158+
This runs your Application locally, simulating the Azion platform. See [Troubleshooting](/en/documentation/products/guides/opennext/troubleshooting/) for tips on debugging and log monitoring.
159+
160+
---
161+
162+
### Deployment
163+
164+
Deploy your app to Azion Web Platform:
165+
166+
```sh
167+
azion deploy
168+
```
169+
170+
Or use the Azion CLI to deploy to Azion Web Platform using Local Deployment:
171+
172+
```sh
173+
azion deploy --local
174+
```
175+
176+
---
177+
178+
### Best Practices & Troubleshooting
179+
180+
- See [Known Issues](/en/documentation/devtools/azion-edge-runtime/compatibility/nextjs/#known-issues) for important config notes.
181+
- See [Troubleshooting](/en/documentation/products/guides/opennext/troubleshooting/) for local dev, logging, and debugging tips.
182+
- Explore [Examples](/en/documentation/devtools/azion-edge-runtime/compatibility/nextjs/#examples) for starter projects and templates.
183+
- For advanced caching, see [Caching](/azion/caching).

0 commit comments

Comments
 (0)