Introducing Edgio Applications v7Find out what's new.


This guide shows you how to deploy a Next.js application to Edgio.


Next.js offers two different file-based routing schemes you can use to build your app. See the Pages Router and App Router sections of the Next.js documentation for more information. Edgio supports both routing schemes with examples of each below:

Supported Features

Edgio supports all of the most powerful features of Next.js, including:


Integration with Next requires:

Install the Edgio CLI

If you have not already done so, install the Edgio CLI.
1npm i -g @edgio/cli@latest

Getting Started

Create a Next.js Application

If you don’t already have a Next.js application, you can create one using:
1npx create-next-app@latest

Initializing your Project

Initialize your project for use with Edgio by running the following command in your project’s root directory:
1cd my-next-app
2edgio init --edgioVersion latest
This will automatically add all of the required dependencies and files to your project. These include:
  • The @edgio/cli package - Allows you to control Edgio through project-local CLI.
  • The @edgio/core package - Allows you to declare routes and deploy your application to Edgio.
  • The @edgio/prefetch package - Allows you to configure a service worker to prefetch and cache pages to improve browsing speed.
  • The @edgio/devtools package - Allows you to monitor the caching and prefetching functionality.
  • The @edgio/next package - Provides router middleware that automatically adds Next.js pages and api routes to the Edgio router.
  • The @edgio/react package - Provides a Prefetch component for prefetching pages.
    • edgio.config.js - Contains various configuration options for Edgio.
  • routes.js - A default routes file that proxies all requests to the server. Update this file to add caching or proxy some URLs to a different origin.
  • sw/service-worker.js - A service worker implemented using Workbox.

Config Options

In the generated edgio.config.js file, you can customize how Edgio builds and runs your Next.js application. Using the next key, you can configure the following options:
generateSourceMapsOutput sourcemaps so that stack traces have original source filenames and line numbers when tailing the logs in the Edgio Console.true
disableImageOptimizerDisables the Edgio image optimizer and allows to use the Next’s built in image optimizer. false
disableDevtoolsDisables the Edgio development tools widget on the site. false
disableServiceWorkerDisables the build of the service worker.false
forceServerBuildForces the @edgio/next connector to use the server build. This config option replaces the NEXT_FORCE_SERVER_BUILD env variable.false
optimizeServerBuildOptimizes the server build by bundling all server assets and decreasing the overall startup time. This option has no effect on apps with the Edgio cloud build. This option is set to false for Next 13.x apps.true
proxyToServerlessByDefaultReduces the number of generated rules by adding the default catch-all rule that proxies all requests to Next.js to the Edgio cloud. Set this option to false if you want to proxy all unmatched pages to a different origin.true
enforceTrailingSlashAdds rules with Next’s internal redirects that either add or remove a trailing slash. When set to false, the redirect is performed only by the Next.js server itself and doesn’t affect other origins.true

Edgio Next.js Plugin

Edgio provides the following plugin for Next.js. This plugin is automatically added to your project when you run edgio init.
If your project does not have a next.config.js file, one will automatically be added when you run edgio init. Doing so adds the following plugin:

withEdgio (required)

The withEdgio plugin optimizes the Next.js build for running on Edgio. It is required to deploy your application on Edgio.
If your project already has this config file, you need to add these plugins yourself.
1const { withEdgio } = require('@edgio/next/config')
3module.exports = withEdgio({
4 // Next.js config options

Edgio Devtools

To understand better the caching mechanism, you can add Edgio Devtools to see the caching metrics. Add the following code to your _app.tsx file:
1import {useDevtools} from '@edgio/react';
3const MyApp = ({Component, pageProps}) => {
4 useDevtools();
5 // ... rest of your _app.tsx code

Running Locally

Test your app with the Sites on your local machine by running the following command in your project’s root directory:
1edgio dev


Deploy your app to the Sites by running the following command in your project’s root directory:
1edgio deploy
Your initial CDN-as-code deployment will generate system-defined origin configurations along with those defined within your edgio.config.js. Learn more about system-defined origins.
See Deployments for more information.


The edgio init command adds a service worker based on Workbox at sw/service-worker.js. If you have an existing service worker that uses workbox, you can copy its contents into sw/service-worker.js and simply add the following to your service worker:
1import { Prefetcher } from '@edgio/prefetch/sw';
3new Prefetcher().route();
The above code allows you to prefetch pages from Edgio’s edge cache to significantly improve browsing speed. To prefetch a page, add the Prefetch component from @edgio/react to any Next.js Link element. The following example shows you how to prefetch JSON data from getServerSideProps or getStaticProps using the createNextDataUrl function from @edgio/next/client.
1import {Prefetch} from '@edgio/react';
2import Link from 'next/link';
3import {useRouter} from 'next/router';
4import {createNextDataURL} from '@edgio/next/client';
6export default function ProductListing({products}) {
7 const {locale} = useRouter(); // you can omit this if you're not using localization
9 return (
10 <ul>
11 {, i) => (
12 <li key={i}>
13 <Link href={product.url} passHref>
14 <Prefetch
15 url={createNextDataURL({
16 href: product.url,
17 locale, // you can omit this if you're not using localization
18 routeParams: {
19 // keys must match the param names in your next page routes
20 // So for example if your product page is /products/[productId].js:
21 productId:,
22 },
23 })}>
24 <a>
25 <img src={product.thumbnail} />
26 </a>
27 </Prefetch>
28 </Link>
29 </li>
30 ))}
31 </ul>
32 );
35export async function getServerSideProps({params: {id}}) {
36 const products = await fetch(/* fetch from your api */).then((res) =>
37 res.json()
38 );
40 return {
41 props: {
42 products,
43 },
44 };
The Prefetch component fetches data for the linked page from Edgio’s edge cache and adds it to the service worker’s cache when the link becomes visible in the viewport. When the user taps on the link, the page transition will be instantaneous because the browser won’t need to fetch data from the network.

Registering the Service Worker

To enable prefetching, you need to register the service worker in your app. You can skip this step if your app is already using a service worker. If not, add the following code to your pages/_app.js file:
1import {useServiceWorker} from '@edgio/react';
2const MyApp = ({Component, pageProps}) => {
3 useServiceWorker({
4 // set to `true` to install the service worker in development mode
5 dev: false,
6 });
7 // ... rest of your _app.js code
Starting with Next.js 13, when the app directory is used, adding useServiceWorker hook may break the build, as all pages in the app directory are by default server components. In order to avoid this, hooks must be placed in a client-only component. To do this, add use client directive at the top of the component.


Edgio supports Next.js’s built-in routing scheme. The default routes.js file created by edgio init sends all requests to Next.js:
1import {nextRoutes} from '@edgio/next';
2import {Router} from '@edgio/core/router';
4export default new Router()
5 // By default send all requests to the Next.js app
6 .use(nextRoutes);

Routing Requests to Other Origins

To route certain requests to an origin other than your Next.js app, first add the origin to edgio.config.js:
1module.exports = {
2 connector: '@edgio/next',
3 origins: [
4 {
5 name: 'api',
6 hosts: [
7 {
8 scheme: 'match',
9 location: [
10 {
11 hostname: '',
12 },
13 ],
14 },
15 ],
16 },
17 ],
Then use the match method to define a route and specify the origin option:
1export default new Router()
2 // By default send all requests to the Next.js app
3 .use(nextRoutes)
4 // Override the default behavior to route requests to /api/* to the api origin
5 .match('/api/:path*', {
6 origin: {
7 set_origin: 'api',
8 },
9 });

Preview Mode

To be able to use Preview Mode while being able to cache the respective pages, update your routes to match the requests that contain the two cookies __prerender_bypass & __next_preview_data, and send those to the Edgio cloud for rendering.
1import {Router} from '@edgio/core/router';
2import {nextRoutes} from '@edgio/next';
4export default new Router()
5 // By default send all requests to the Next.js app
6 .use(nextRoutes)
7 // Disable caching for preview mode
8 .match(
9 {
10 cookies: {
11 __prerender_bypass: /.*/g,
12 __next_preview_data: /.*/g,
13 },
14 },
15 {
16 caching: {
17 bypass_cache: true,
18 bypass_client_cache: true,
19 },
20 }
21 );

Rewrites and Redirects

The nextRoutes plugin automatically adds routes for rewrites and redirects specified in next.config.js. Redirects are served directly from the network edge to maximize performance.


The easiest way to add edge caching to your Next.js app is to add caching routes after nextRoutes. For example, imagine you have /pages/p/[productId].js. Here’s how you can SSR responses as well as cache calls to getServerSideProps:
1export default new Router()
2 .use(nextRoutes)
3 // Products - SSR
4 .get('/p/:productId', {
5 caching: {
6 // Ignore the cache-control header generated by Next.js
7 ignore_origin_no_cache: [200],
8 // cache at the edge for one day
9 max_age: '1d',
10 // continue to serve stale responses for up to one hour while revalidating
11 stale_while_revalidate: '1h',
12 // don't cache the response in the browser
13 bypass_client_cache: true
14 },
15 })
16 // Products - getServerSideProps
17 .get('/_next/data/:version/p/:productId.json', {
18 caching: {
19 // Ignore the cache-control header generated by Next.js
20 ignore_origin_no_cache: [200],
21 // cache at the edge for one day
22 max_age: '1d',
23 // continue to serve stale responses for up to one hour while revalidating
24 stale_while_revalidate: '1h',
25 // disable caching in the browser's http cache
26 bypass_client_cache: true
27 // instead cache in the browser using the service worker for one hour - this allows us to prefetch API calls
28 service_worker_max_age: '1h'
29 },
30 })

Preventing Next.js pages from being cached by other CDNs

If you are using a CDN in front of Edgio and you want to prevent it from caching Next.js pages, you can do so by setting the bypass_client_cache option to true:
1new Router()
2 // By default send all requests to the Next.js app
3 .use(nextRoutes)
4 // Disable caching in downstream CDNs for a specific page
5 .get('/my-private-page', {
6 caching: {
7 bypass_client_cache: true, // this will prevent downstream CDNs from caching the response
8 },
9 });

Using next-i18next

The next-i18next package is a popular solution for adding localization to Next.js apps. It has some issues when running in Edgio cloud deployments, but you can work around these:
First, you need to not use the default name for the next-i18next.config.js file. We recommend renaming it i18next.config.js. When you use the default name, next-i18next will try to load the config when the Cloud Function starts and since it is not bundled with the app, it will fail.
Then, you need to explicitly provide the config to appWithTranslation and serverSideTranslations.
So in your pages/_app.js:
1export default appWithTranslation(MyApp, require('../i18next.config')); // <~ need to explicitly pass the config here
and in your pages:
1export async function getStaticProps({locale}) {
2 return {
3 props: {
4 ...(await serverSideTranslations(
5 locale,
6 ['common', 'footer'],
7 require('../i18next.config') // <~ need to explicitly pass the config here.
8 )),
9 // Will be passed to the page component as props
10 },
11 };
Make sure you also import the config correctly with the new name into your next.config.js:
1const { withEdgio } = require('@edgio/next/config')
2const { i18n } = require('./i18next.config')
4module.exports = withEdgio({
5 i18n,
6 });
Finally, you will need to update your edgio.config.js to include where the locale files are stored. Here is an using the default location /public:
1module.exports = {
2 connector: '@edgio/next',
4 serverless: {
5 include: ['public/**/*'],
6 },

Image optimizer

By default, Next.js image optimizer is replaced by our image optimizer, which is available in all build modes. You can disable it and use the built-in Next.js image optimizer instead by adding disableImageOptimizer: true to the next config in the edgio.config.js file.
1module.exports = {
2 next: {
3 disableImageOptimizer: true,
4 },
Note that Next.js apps prior to 12.x built with the serverless target (see Next.js 12.x deprecation notes) don’t include a Next.js image optimizer. Disabling our image optimizer without providing an alternative may cause them to fail.

Cloud Bundling

Next.js has continued to improve how it bundles production builds for deployment on serverless architectures. Edgio takes advantage of these improvements by applying different configuration options depending on the version of Next.js being used:
VersionNext.js configs applied
Next.js < 12.2.0target: 'experimental-serverless-trace'
Next.js >= 12.2.0output: 'standalone'
For backwards compatibility, Edgio will also respect target: 'serverless' in your next.config.js for Next.js versions prior to 12.0.0.
Note that NextRouter.render404 and renderNextPage are retired when using Next.js 12.2.0+. Requests are delegated to a Next.js server instance which will handle determining which page to render based on the request. Prior use cases should now be achieved via using Next.js redirects and rewrites.

Support for Next.js Middleware (BETA)

Edgio supports Next.js middleware starting with Next.js 12.2.0.
When using Next.js middleware it should be noted that the middleware functions are only executed within the Edgio cloud, after the edge cache. Middleware that you want to execute on each request needs to have caching disabled explicitly for the route on which the middleware is enabled. Some Middleware use cases such as rewriting the request to another route would be fine to cache. These use cases need to be evaluated on a per route basis with caching enabled/disabled based on the desired result.

Runtime Variables Configuration

Edgio supports runtime variables in serverRuntimeConfig and publicRuntimeConfig properties of next.config.js. For more information, visit the Next.js Runtime Configuration documentation.

Related Resources

Below are a few helpful resources that may be referenced in this guide for configuring, managing, and serving your property on Edgio: