# opennextjs-netlify: the adapter that builds Next.js for Netlify

> This repository holds the packages that make Next.js run on Netlify, published to npm as @netlify/plugin-nextjs and used automatically during Netlify builds. Most teams never install it, and that is the point, but the plugin and toml entry are there for teams that need to pin a version or wire up older releases.

**opennextjs/opennextjs-netlify** — Open Next.js adapter for Netlify

- Repository: https://github.com/opennextjs/opennextjs-netlify
- Website: https://opennext.js.org/netlify
- Stars: 854 · Forks: 117
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/opennextjs-opennextjs-netlify

## A repository you probably will not install

This project is described as an Open Next.js adapter for Netlify, and the README says the package handles the build process and creates the runtime environment for Next.js sites on Netlify. The next sentence is the one that explains the whole design: you should not normally need to install it yourself, as it is used automatically during builds of Next.js sites.

The reason is that Next.js is supported natively on Netlify, and in most cases you will not need to install or configure anything. What this repository actually contains is the packages used to support Next.js on Netlify. So the public artifact is the npm package @netlify/plugin-nextjs, and the repository is where that package is built and maintained, hosted under the opennextjs organization with the homepage at opennext.js.org/netlify.

For an engineer evaluating the project, the practical question is therefore not whether to use it but whether to depend on it explicitly. Most teams will never touch it. Teams that want to control the version, who need to understand what happens during a build when something breaks, or who are moving off the older runtime need to read this code and the package metadata.

The README also states where the user facing documentation lives, the Netlify docs for using Next.js on Netlify, so the split between adapter internals and product documentation is deliberate.

## The two ways to install, and why the npm route exists

The Next.js Runtime installs automatically for new Next.js sites on Netlify, but there are two manual routes, and the README is explicit about which one to prefer for which reason.

The first is the UI. You go to the Netlify plugin page, choose the site to install the Next.js Runtime on, and the documentation recommends this method because you benefit from auto-upgrades to important fixes and feature updates. In other words, the Netlify platform owns the version, and you get fixes without a pull request.

The second is npm, which requires adding the package as a development dependency:

```shell
npm install -D @netlify/plugin-nextjs
```

and then declaring it in netlify.toml:

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

The stated reason for choosing this route is that it is recommended if you wish to pin the Next.js Runtime to a specific version. That is the entire trade-off: the UI route buys you automatic upgrades, the npm route buys you version control over the runtime at the cost of owning the upgrade yourself.

That trade is worth understanding because a Next.js build that silently changes runtime version can break in ways that look like application bugs. A team that has ever been burned by a platform upgrade taking a different route than the one that gave them auto-updates.

## Version routing: v5 today, v4 for anything older

The version story is short and has hard edges. The prerequisites are Next.js 13.5 or later, Node.js 18 or later, and the latest version of the Netlify CLI.

Anything older is routed to the previous major. If you are using Next.js 10 to 13.4, or Node.js below 18, you must use v4 of the Next.js Runtime. The v4 README and the v4 runtime documentation live in the older netlify/next-runtime repository at the v4 tag, so the split is between two repositories as well as two major versions.

The end of life statement is unambiguous: v4 will only receive security fixes and critical bug fixes. There is no feature work and no compatibility work going into v4. Upgrading from v4 to v5 is directed to the v5 documentation rather than a migration guide in this repository, which tells you the upgrade path is documented on the platform side.

The release cadence gives some indication of where the effort is going. The listed tags are v5.16.3 from 2026-10-19, v5.16.2 from 2026-10-05 and v5.16.1 from 2026-09-30, so the v5 line is taking patch releases at a steady rate. The repository is not archived and the last push was on 2026-10-19.

The practical consequence for an upgrade plan is simple. If your project is on Node 16 or Next.js 12, this adapter is not the place to start, because staying on v4 means staying on a branch that only gets security fixes.

## What the package actually ships

The package metadata describes the artifact more precisely than the README does. The npm name is @netlify/plugin-nextjs, the version is 5.16.3, the description is Run Next.js on Netlify, and the module is ESM with the type field set to module and the main entry at ./dist/index.js.

The files array is the interesting part, because it explains how the plugin reaches into a Netlify build. The published tarball contains dist, an edge-runtime directory, and manifest.yml, with several exclusions carved out of the edge runtime bundle: deno.json and deno.lock are left out, as are test files under the edge runtime and a lib/fixture directory. The presence of a Deno configuration in the tree tells you the edge runtime pieces are shaped for a Deno style runtime, and the exclusions exist so the published package stays small.

The engines field asks for node >=18.0.0, which is the machine readable form of the version routing described in the README.

The build and test scripts show how the project is developed. The build runs node ./tools/build.js with a watch variant, lint runs eslint over src with a zero warning limit, formatting is handled by prettier, and type checking is tsc --noEmit. Tests are split into vitest projects named unit, integration and smoke, with playwright handling the end to end suite. There is a run-local-test.sh script at the repository root, and a tests/prepare.mjs script that the pretest hook runs after a build, which is how the integration tests get their fixtures.

## The repository layout tells you this is more than a thin wrapper

Looking at the top level entries changes the impression of scale. Alongside the expected src, tests, scripts and tools directories there is an edge-runtime directory, a turbofan directory, a report directory, an e2e-report directory and a manifest.yml, plus a playwright.config.ts and a vitest.workspace.ts at the root.

The turbofan directory name is not explained anywhere in the README, so treat it as an internal component of unknown purpose rather than something to build on. What the layout does establish is that this is a substantial adapter rather than a thin shim, and that the team keeps separate suites for unit, integration, smoke and browser level behaviour, with reporting directories checked in for the end to end and report outputs.

The project also carries the usual governance files. There is a release-please-config.json and a .release-please-manifest.json, which is how versions are cut and tagged, and it lines up with the patch level tags in the release history. There is a renovate.json, so dependency updates are automated, and a CHANGELOG.md, CONTRIBUTING.md and LICENSE file. The code style is enforced through .eslintrc.cjs and .prettierrc.cjs with matching ignore files, and .editorconfig for whitespace.

Feedback goes to two places. Bugs go to the GitHub issue tracker on this repository, and feature requests and comments go to the discussion board. The fact that the issue tracker lives under the opennextjs organisation while the npm package is scoped to @netlify is worth remembering when you go looking for support.

## When the adapter is the wrong tool

There are clear cases where reaching for this project solves nothing.

If you deploy somewhere other than Netlify, this adapter is irrelevant by definition, and the opennext.js.org homepage suggests the Open Next.js family covers other platforms through separate adapters. If you are still on Next.js below 13.5, you are on the v4 branch with security fixes only, and the better move is a framework and Node upgrade rather than a runtime pinning exercise.

If your build is not actually failing, the main cost of this project is unnecessary coupling. Installing the plugin from npm to pin a version means you own the upgrade path, including reading release notes for a package you did not write. For a team that has no problem with the runtime, the UI route is the lower risk choice and the README recommends it.

The other case worth naming is a build failure whose cause is not in the adapter. Next.js builds fail for many reasons, and when the failure is in application code, in a dependency, or in a configuration file, no amount of runtime version pinning helps. The documentation point about opening an issue is for genuine runtime bugs, and a good first step is to reproduce the build locally with the Netlify CLI, which is listed as a prerequisite.

One documentation gap is worth flagging. The README does not explain what the manifest.yml at the repository root and in the published files does, nor how the plugin hooks into the Netlify build lifecycle, so if you need to reason about the adapter from the outside, the published package and the platform documentation are the places to look.

## Conclusion

Adopt this adapter as it is by default if you deploy Next.js to Netlify, since the runtime is installed automatically and needs no configuration. Reach for the manual npm install only when you need to pin the version in netlify.toml, and treat the v4 line as a security-fix-only branch you should be planning to leave. Verify first that your Next.js version is 13.5 or later and your Node.js is 18 or later, since anything older is routed to v4, and confirm that the plugin entry you add to netlify.toml matches the v5 package name.

## FAQ

### Do I need to install the Next.js Runtime on Netlify manually?

Usually not. The README says the Next.js Runtime installs automatically for new Next.js sites on Netlify, and that in most cases you will not need to install or configure anything. Manual installation is for teams that want to pin a specific version.

### How do I pin the Next.js Runtime version with netlify.toml?

Add the package as a dev dependency with `npm install -D @netlify/plugin-nextjs`, then declare it in netlify.toml under a `[[plugins]]` entry with `package = "@netlify/plugin-nextjs"`. The README recommends this method specifically when you want to pin the runtime version.

### Which Next.js and Node.js versions does opennextjs-netlify support?

The prerequisites are Next.js 13.5 or later and Node.js 18 or later, plus the latest Netlify CLI. If you are on Next.js 10 to 13.4 or Node.js below 18 you must use v4 of the Next.js Runtime.

### Will v4 of the Next.js Runtime keep getting features?

No. The README states that v4 will only receive security fixes and critical bug fixes, and the v4 documentation lives in the older netlify/next-runtime repository at the v4 tag. Upgrading from v4 to v5 is directed to the v5 documentation.

### What license is the Netlify Next.js plugin released under?

MIT. The package.json declares the license field as MIT, the README carries an MIT licence badge for the npm package, and a LICENSE file sits at the repository root.

## Sources

- [License: MIT](https://github.com/opennextjs/opennextjs-netlify/blob/main/LICENSE)
- [opennextjs/opennextjs-netlify on GitHub](https://github.com/opennextjs/opennextjs-netlify)
- [Project website](https://opennext.js.org/netlify)
- [README](https://github.com/opennextjs/opennextjs-netlify/blob/main/README.md)
- [Releases](https://github.com/opennextjs/opennextjs-netlify/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opennextjs-opennextjs-netlify