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.

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

Install the Azion Adapter:

npm install @aziontech/opennextjs-azion@latest

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 /azion/caching for advanced options
});

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.

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.

Set Up Caching and Storage:

Example Azion config:

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.

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

See Known Issues for important config notes.
See Troubleshooting for local dev, logging, and debugging tips.
Explore Examples for starter projects and templates.
For advanced caching, see Caching.