Repository files navigation

Next.js is supported natively on Netlify, and in most cases you will not need to install or configure anything. Thisrepo includes the packages used to support Next.js on Netlify.

If you build on Netlify, the Next.js Runtime will work with no additional configuration. However if you are building anddeploying locally using the Netlify CLI, you must deploy usingnetlify deploy --build. Running the build and deploycommands separately will not work, because the Next.js Runtime will not generate the required configuration.

If you usenext/image, your images will be automaticallyoptimized at runtime, ensuring that they are served at the best size and format. The image will be processed on thefirst request which means it may take longer to load, but the generated image is then cached and served as a static fileto future visitors. By default, Next.js will deliver WebP images if the browser supports it. WebP is a modern imageformat with wide browser support that will usually generate smaller files than PNG or JPG. Additionally, you can enableAVIF format, which is often even smaller in filesize than WebP. The drawback is that with particularly large images,AVIF images may take too long to generate, and the function times-out. You can configurethe supported image formats in yournext.config.js file.

It is possible to run image content negotiation on the edge. This allows images to be processed on the first request,and then, in future loads, served from cache on the edge.

In order to deliver the correct format to a visitor's browser, this uses a Netlify Edge Function. In some cases yoursite may not support Edge Functions, in which case it will instead fall back to delivering the original file format.

To turn on Edge image handling for Next/Image, set the environment variableNEXT_FORCE_EDGE_IMAGES totrue

Should you wish to return custom response headers on images handled by thenetlify-ipx package, you can add them within your project'snetlify.tomlby targeting the/_next/image/* route:

[[headers]]  for = "/_next/image/*"  [headers.values]    Strict-Transport-Security = "max-age=31536000"    X-Test = 'foobar'

If you wish to disable the use of the image loader which is bundled into the runtime by default, set theDISABLE_IPXenvironment variable totrue.

This should only be done if the site is not usingnext/image or is using a different loader (such as Cloudinary orImgix).

See theNext.js documentation for image loaderoptions.

Next.js Middleware works out of the box on Netlify. By default, middleware runs using Netlify Edge Functions. For legacysupport for running Middleware at the origin, set the environment variableNEXT_DISABLE_NETLIFY_EDGE totrue. Beaware that this will result in slower performance, as all pages that match middleware must use SSR.

For more details on Next.js Middleware with Netlify, see themiddleware docs.

Due to how the site configuration is handled when it's run using Netlify Edge Functions, data such aslocale anddefaultLocale will be missing on thereq.nextUrl object when runningnetlify dev.

However, this data is available onreq.nextUrl in a production environment.

If you are using a monorepo you will need to changepublish to point to the full path to the built.next directory,which may be in a subdirectory. If you have changed yourdistDir then it will need to match that.

If you are using Nx, then you will need to pointpublish to the folder insidedist, e.g.dist/apps/myapp/.next.

The Next.js Runtime fully supports ISR on Netlify. For more details seethe ISR docs.

Note that Netlify has a minimum TTL of 60 seconds for revalidation.

Currently when hitting a non-prerendered path withfallback=false it will default to a 404 page. You can now changethis default setting by using the environemnt variableLEGACY_FALLBACK_FALSE=true. With the environment variable set,those non-prerendered paths will now be routed through using the ISR Handler and will allow you to add redirects forthose non-prerendered paths.

If you are usingnext export to generate a static site, you do not need most of the functionality of this Next.jsRuntime and you can remove it. Alternatively you canset the environment variableNETLIFY_NEXT_PLUGIN_SKIP totrue and the Next.js Runtime will handle caching but won't generate any functions forSSR support. Seedemos/next-export for anexample.

Netlifyasset optimization should not be used with Next.jssites. Assets are already optimized by Next.js at build time, and doing further optimization can break your site. Ensurethat it is not enabled atSite settings > Build & deploy > Post processing > Asset optimization.

The Next.js Runtime works by generating three Netlify functions that handle requests that haven't been pre-rendered.These are___netlify-handler (for SSR and API routes),___netlify-odb-handler (for ISR and fallback routes), and_ipx (for images). You can see the requests for these inthe function logs. For ISR and fallback routes you will not see any requeststhat are served from the edge cache, just actual rendering requests. These are all internal functions, so you won't findthem in your site's own functions directory.

The Next.js Runtime will also generate a Netlify Edge Function called 'ipx' to handle image content negotiation, and ifEdge runtime or middleware is enabled it will also generate edge functions for middleware and edge routes.

The Next.js Runtime installs automatically for new Next.js sites on Netlify. You can also install it manually in thefollowing ways:

You can go to theUI and choose the site to installthe Next.js Runtime on. This method is recommended because you will benefit from auto-upgrades to important fixes andfeature updates.

npm install -D @netlify/plugin-nextjs

...then add the following to yournetlify.toml file:

[[plugins]]package ="@netlify/plugin-nextjs"

This method is recommended if you wish to pin the Next.js Runtime to a specific version.

If you previously set these values, they're no longer needed and should be removed:

• distDir in yournext.config.js
• node_bundler = "esbuild" innetlify.toml
• external_node_modules innetlify.toml
• The environment variableNEXT_USE_NETLIFY_EDGE can be removed as this is now the default

Theserverless andexperimental-serverless-trace targets are deprecated in Next.js 12, and all builds with thisNext.js Runtime will now use the defaultserver target. If you previously set the target in yournext.config.js, youshould remove it.

If you currently use redirects or rewrites on your site, seethe Rewrites and Redirects guide forinformation on changes to how they are handled in this version. In particular, note that_redirects and_headersfiles must be placed inpublic, not in the root of the site.

If your site uses pnpm to manage dependencies, currently you mustenable public hoisting. The simplest way to do this is to create a.npmrc file in the root of your project with the content:

public-hoist-pattern[]=*

To run the tests, ensure that the dependencies are installed as follows:

npm install

Then run the tests:

npmtest

In order to run the end-to-end (E2E) tests, you'll need to be logged in to Netlify. You can do this using theNetlify CLI with the command:

netlify login

Alternatively, you can set an environment variableNETLIFY_AUTH_TOKEN to a valid Netlify personal access token. Thiscan be obtained from theNetlify UI.

Then run the E2E tests if logged in:

npm run test:next

Or if using an access token:

NETLIFY_AUTH_TOKEN=your-token-here npm run test:next

Note: The E2E tests will be deployed to a Netlify owned site. To deploy to your own site then set the environmentvariableNETLIFY_SITE_ID to your site ID.

If you think you have found a bug in Next.js on Netlify,please open an issue. If you have comments or feature requests,see the discussion board