Get Started With OpenNext

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.

View as Markdown

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

Creating a New Next.js App

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

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:

Existing Next.js Apps

  1. Install the Azion Adapter:
npm install @aziontech/opennextjs-azion@latest
  1. Configure open-next.config.ts:

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

import { defineAzionConfig } from "@aziontech/opennextjs-azion";
export default defineAzionConfig({
// See https://www.azion.com/en/documentation/products/build/applications/cache/ for advanced options
});
  1. Update tsconfig.json:

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:

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

See 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.
  1. Set Up Caching and Storage:

Example Azion config:

AzionCache
Type definition for the cache configuration.

Properties:

PropertyTypeDescription
namestringName of the cache configuration.
stale?booleanWhether to allow stale content.
queryStringSort?booleanWhether to sort query string parameters.
methods?CacheMethodsHTTP methods to cache.
post?booleanWhether to cache POST requests.
options?booleanWhether to cache OPTIONS requests.
browser?BrowserCacheConfigBrowser cache settings.
browser.maxAgeSecondsnumber | stringMaximum age for browser cache in seconds.
edge?EdgeCacheConfigCache settings.
edge.maxAgeSecondsnumber | stringMaximum age for cache in seconds.
cacheByCookie?CacheByCookieConfigCache by cookie settings.
cacheByCookie.option’ignore’ | ‘varies’ | ‘whitelist’ | ‘blacklist’Cache by cookie option.
cacheByCookie.list?string[]List of cookies to use for caching.
cacheByQueryString?CacheByQueryStringConfigCache 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.
// 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 for local development:

azion dev

This runs your Application locally, simulating the Azion platform. See Troubleshooting for tips on debugging and log monitoring.

Deployment

Deploy your app to Azion Web Platform:

azion deploy

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

azion deploy --local

Best Practices & Troubleshooting