[RFC] Plugins

[timneutkens]

Authored together with @ijjk.

Goals

• Provide an official plugin system for Next.js
• Allow hooking into different parts of the Next.js lifecycle
• Provide the right limits for plugins to prevent them from de-optimizing applications
• Warn users when a plugin is being inefficient
• Provide a zero-config approach to plugins
• Provide code splitting for plugins

Background

Over time the Next.js examples directory has grown to 210+ examples. These examples show how to integrate external libraries for styling, error reporting, data fetching, and many other applications.

Most of these examples require a bit of configuration in various parts of Next.js, for example, in _document, _app, or pages. And sometimes the implementation details have to match exactly the example otherwise the library behaves in a different way. We've seen this for the example with material-ui that has a flash of unstyled content if _document is not implemented.

There are also examples that are using getInitialProps where it's not always needed, one of the examples of this is the redux example. It currently requires having getInitialProps which causes all pages to opt-out of automatic static rendering.

To solve these issues and provide an overall better developer experience we intend to introduce a plugin system.

Plugins will be able to hook into specific lifecycle parts of Next.js.

For example, to execute a specific bit of code after hydration happens or to inject a script like Google Analytics into the body of every page.

The main goal for the plugin system will be to make you more productive while preserving the Next.js production performance characteristics.

One way we're trying to achieve this is that attached lifecycle methods are automatically code-split in a similar fashion as pages.

This new plugins system will provide you with the best developer experience when integrating libraries and we're excited to see the new ways of integrating and extending Next.js' functionality this system will enable.

Proposal

To provide a seamless plugin experience, Next.js will add built-in support for auto-detecting packages with the naming convention @next/plugin-, next-plugin-, or @<scope>/next-plugin-. We will also investigate allowing local plugins in a plugins or next-plugins directory that don't require being installed.

Each of these plugins will have a meta field named nextjs in their package.json that gives us some extra information about the plugin like the required env values it relies on.

// @next/plugin-google-analytics#package.json
{
  "name": "@next/plugin-google-analytics",
  "version": "9.1.2-canary.1",
  "nextjs": {
    "name": "Google Analytics",
    "required-env": ["GA_TRACKING_ID"]
  },
  "peerDependencies": {
    "next": "*"
  }
}

The only other required step for a plugin is to have a src directory with the lifecycle methods it wants to hook into.

To start, we explored what it would take to create a Google Analytics plugin and a Sentry plugin. Creating these example plugins gave us insight into the lifecycle methods that were needed.

Currently exposed lifecycle methods

The naming scheme for lifecycle methods will be based on:

name + '-' + context

name will be based on the lifecycle, potentially prefixed by on if it's an event.

The context will be client, server or build. It's appended at the end of the file name so that if a lifecycle is available on both client and server it will be sorted together in editors.

Some of the initial methods that come to mind:

// on-init-client.js
export default async function onInitClient({ router }): void {
  // called on client init, before hydration
}

// on-error-client.js
export default async function onErrorClient({ err }): void {
  // called when an error occurs during render on the client
}

// on-error-server.js
export default async function onErrorServer({ err }): void {
  // called when an error occurs during render on the server
}

// document-head-tags-server.js
export default function headTags(DocumentCtx): Promise<ReactElement[]> {
  // called when rendering the initial document, allows adding tags to the head
  return (
    <>
      <script src="googleanalytics.com/code.js" async />
    </>
  );
}

// document-body-tags-server.js
export default async function bodyTags(DocumentCtx): Promise<ReactElement[]> {
  // called when rendering the initial document, allows adding tags to the body
  return (
    <>
      <script src="example.com/body.js" async />
    </>
  );
}

// babel-preset-build.js
module.exports = function babelPreset({ plugins, presets }, config): {
  // Babel config that will be merged inside next/babel
}

An example folder structure for one of these plugins would look like this

package.json
src/
  on-error-client.js
  on-error-server.js
  on-init-client.js
  on-init-server.js

Following this structure allows Next.js to provide a zero-config experience for plugins. Not only that, but it also allows us to code split these methods efficiently, only loading the parts of a plugin that are necessary at a specific point. We can also detect which parts of a plugin are being less efficient since they are all their own file and warn users of this.

Providing information to plugins

Although we aim to make adding plugins to a project as simple as possible, some plugins still require some information like a token or an id.

To handle this, we allow you to provide these values using the current env config in next.config.js and the values will be injected into the plugin where needed during build time.

// next.config.js
module.exports = {
  env: {
    GA_TRACKING_ID: "myTrackingId"
  }
};

If a value listed in a plugin's required-env is missing in your next.config.js's env we will error and require you provide these values so that the plugin is able to function correctly. We may need to investigate name spacing these values to prevent collision between plugins.

[Janpot]

Interesting concept. In case you haven't seen it yet, here's an interesting read about some considerations around plugin systems that I think apply here as well. How would you handle ordering and plugins depending on each other, and with that, deduplication?

[flybayer]

This'll be awesome!

We also need ability to modify the webpack config, for example to make next-plugin-react-native-web.

Perhaps plugins can use the exact same next.config.js format for adding any modifications needed there (including things like assetPrefix).

[franklinjavier]

Love it 👊

[flybayer]

What I need for next-plugin-webextenson

Context: I am using Next.js to power a Chrome/Firefox extension

I'm currently using a custom server during development to:

1. Write each page's html to disk on (a) server start and (b) page change
2. Copy all files in public to the same directory as the above pages

Here's what I need:

1. A hook into app.renderToHTML() that provides me with req, res, and output html
   • I'll use this to write that html to disk
2. A hook that provides me all the pages along with app
   • I'll use this on startup to call app.renderToHTML() for each page
   • This is essential because I can't wait for a client to request a page.
3. A hook on startup so I can copy all files in public to the same place as the page html files

UPDATE:

The absolute minimum I need is:

1. A development-only hook into app.renderToHTML() that provides me with req, res, and output html
   • I'll use this to write that html to disk
2. A development-only hook after server boot that provides app
   • I'll use this to do everything else I need like copy certain files, etc.

[Jarred-Sumner]

This looks really cool!

If a value listed in a plugin's required-env is missing in your next.config.js's env we will error and require you provide these values so that the plugin is able to function correctly.

I could see erroring when missing env vars being a source of frustration — sometimes, when working quickly, you install some packages but don’t end up using them. The next time the developer restarts their server in development, it would error.

Perhaps instead, it could warn in development when the server first loads, skip loading the plugin, and then error during the production build? With a message that says to either provide the missing env vars or uninstall the plugin (with the package name, and ideally, a command to copy paste to uninstall)

Ideally, plugins would be able to optionally provide a label saying how to find the values for the env var, so that fixing the error is more clear.

But feel free to ignore this, this is really cool and maybe this suggestion is premature

[MANTENN]

I think it would be cleaner with hooks, and follow the hooks style. But again that's a matter of preference, and up to debate. Two options would be great.

[kachkaev]

To provide a seamless plugin experience, Next.js will add built-in support for auto-detecting packages with the naming convention @next/plugin- and next-plugin-.

I'd also add autodetection for @<scope>/next-plugin- like in Prettier. This will be useful for company-scoped internal plugins.

With autodetection, I'm curious how to handle cases when order of plugin execution matters. E.g. one might want to make Sentry's onErrorClient / onErrorServer to be outermost even if the same methods are defined by other plugins 🤔 We might need some kind of 'z-index' here, but as with z-index in CSS, assigned values can go a bit out of control one day 😅

[thedankelly]

Can't wait. 👍🏻

[leerob]

I am so excited about this 🎉

Let me know about the Sentry plugin - willing to help out!

[sanishkr]

Great idea. I will appreciate it if a repo link for full fledged sample next-plugin is provided. Also, any timelines on this?

[RichiCoder1]

I share the same concern about loading order, as well as for

The only other required step for a plugin is to have a src directory with the lifecycle methods it wants to hook into.

It'd be nice if this could be configured for libraries that use transpilation so they can output to a separate folder.

Also it might be nice if a plugin could be organized as:

src/
  document/body-tags/server.js
  on-init/client.js
  on-init/server.js

though that may be overkill/perf problematic and a code smell for an overly large plugin.

We will also investigate allowing local plugins in a plugins or next-plugins directory that don't require being installed.

I think this would be super helpful for developing and testing plugins without mucking with linking/node_modules

[ematipico]

It would be great if during the build stage, Next.js would be able to pass the routes of the application:

• posts/:postId
• contact-us

Thanks!

Edit: also, bear in mind that people usually put their final code inside a dist folder as they have plugins made using a different language (TypeScript). Does that mean that these plugins would need to compile their code into the same folder?

[timneutkens]

We also need ability to modify the webpack config, for example to make next-plugin-react-native-web.

We won't be exposing the webpack config to plugins as it's by far the easiest way to cause deoptimization. Instead we'll provide methods for aliasing modules for react-native-web for example.

[timneutkens]

#9133 (comment)

Initially we won't be supporting these as they also sound like pitfalls for deoptimization.

For example:

I'll use this to write that html to disk

Furthermore

A hook that provides me all the pages along with app
I'll use this on startup to call app.renderToHTML() for each page
This is essential because I can't wait for a client to request a page.

This is not possible as in development there is on-demand-entries.

[timneutkens]

#9133 (comment)

It's sort of dangerous to do so though, as it would be easy for you to forget providing environment variables in a certain environment and that would cause the plugin to either be excluded or error out based on the description.

Potentially we could do that behavior in development and fail if the env var is not set in production builds though.

[eric-burel]

Hi, this is probably more a "next step" but something you'd want to consider for plugins is UI. That probably goes beyond the idea of "plugins" to form fully independent "packages".

An example: say I want to implement a debug package, with an admin interface. You'd like it to add pages available for admin users.

That could mean having a "prebuild" or "install" step for plugins, that would allow for more complex file manipulation like adding pages into the users project.

That's not a very good example but you get the point, that could be enhancing Next.js with a blog connected to a 3rd party headless cms for example or stuffs like that.

[eric-burel]

Here is a link to a more detailed reference to what we want to implement in Vulcan with Next: VulcanJS/vulcan-next#3

The issue might not be very clear to non-Meteor/non-Vulcan devs but basically what we try to do is to bring the power of Meteor isomorphic packages and Vulcan dynamic generation (Mongo collection, graphql API, routes and overrideable React components) to what we could call the "static" ecosystem, through Next.

A powerful plugin system in Next means an easier transition for us.

To sum it up, our plugins plugin should be able:

• to create new routes
• to define code that should run at server startup (for example to define Mongoose schema)
• to generate static files in the build folder
• to extend whatever can be extended in Next: _app, _document, pages, api routes, custom server, webpack/babel build, TypeScript build and so on.

Edit: example that inspires us are Apollo Universal Starter Kit package system (it's fully dynamic but the ideas are there) and the idea of CSF in Storybook.

[fev4]

I'm wondering the same as @HaNdTriX (comment link) and would like to understand how this would fit within a page-centered approach.

Would there ever be a need for a plugin to run or be used on certain pages and not others? And if yes, how would this be supported within the context of this RFC?

[chrisrichard]

This is very exciting! We're actually building a framework thing on top of Nextjs static export feature and currently we are completely wrapping Nextjs to be able run our things before and after Nextjs does its things. For now we just import the export function from "next/dist/export".

👍

I've hacked in something in a fork to enable NewRelic monitoring of the export process (ratehub@9a46ba7) and would be great to be able to do this with hooks.

[eric-burel]

Hi guys, if it can be of any help this is my first attempt as loading Material UI and Styled Components as packages. Far from being done, but I've managed to abstract _document enhancing a bit:

Example of a material UI document enhancer
Same for Styled component
And I call them like this in _document

They rely on this common interface:

export interface AppSheetsCollector {
  sheets: { getStyleElement: Function }; // minimum spec to respect for a collector
  enhanceApp: Function; // function used in ctx.renderPage, so the sheet can collect styles
  finally?: Function;
}

This example is limited to stylesheet collection, but could generalize to other things that need to wrap the app, fill a global variable during render and then get the result. (Also, it may be broken or not working as expected.. I'll let it rest during the week-end before checking it back).

[luciano-souza]

Is there any other easier approach to this? Trying to do this, but it is beyond my js programming skills.

[evantahler]

Here's a blog post we wrote about how we are using plugins today! https://www.grouparoo.com/blog/nextjs-plugins

[eric-burel]

After fighting to create some reusable NPM packages for Next, and partly failing to do so (#17262, martpie/next-transpile-modules#120), maybe the first step toward a plugin system would be to write official guidelines about writing NPM packages for Next.

I think in particular about the built step: since the package is meant to be used in a Next app, the build requirements are a bit different than for an usual package. For instance you can ship non transpiled TypeScript code, but you have to take care about not breaking Next.js process.env magic (I think that's similar to what has been presented at the end of the top post?) . Edit: issue already tackling this question of build: #706

[ch99q]

Wrapping of the main app component would be very needy, for plugins wanting to provide data using React Context.

E.g. https://www.gatsbyjs.com/docs/browser-apis/#wrapRootElement
Gatsby has a function called wrapRootElement that works perfectly for this purpose.

Might have skipped it, could not find a comment on it

[flybayer]

Could we get an official update on the status of this RFC and any expected changes/finalization?

[jack-michaud]

I came across this thread trying to write a plugin for Elastic APM.
I'd love to see this snippet from #18272 to make it into the on-error hooks.

It looks like there's a rewrite going on in #20759. Here's hoping there's going to be movement on finalizing plugins at some point..

[giovannibenussi]

What’s the status of this? This for sure will be a game changer for Next.js. I can imagine plugins for authentication, third party services, analytics, telemetry, among others.

[tangye1234]

Disabling plugin system prevent us from upgrating next.js to the latest one. we got bunch of server side and client side initializers, that has been run in the old plugin system. It worked well until 10.3. My point is would you really want to support a plugin system in the future. If not, I’d rather modify all of it now, otherwise I can wait until that is supported.

[leerob]

Update: As others have mentioned, we have removed the previously experimental version of this RFC that was in Next.js. Even though it was marked as experimental and mentioned to not use, some folks still ended up taking it to production, leading to a bad experience for everyone. After extensive testing, we decided we needed to iterate on the API more to satisfy all use cases for plugins for Next.js and to make it extensible for the future.

tl;dr We are still planning to add a plugin system to Next.js.

[sinclairnick]

Hey @leerob do you have any updates on this one? Presumably you'll wait until TurboPack has stabilised before continuing down this path?

[mkilpatrick]

I'm also curious on the status/direction/timeline of this.

[eric-burel]

Hi guys, I am struggling and feeling a bit alone on this:
I want to create NPM packages, for Next.js users, with following requirements :

• being able to expose client-only code (eg smth depending on leaflet or whatever)
• being able to expose server-only code (eg server endpoints)
• being able to expose shared code (typically React components and helpers)
• exposing TypeScript definition
• just enough to support Next.js (usually you want to target other frameworks when building a package, but focusing on Next.js could help having the simplest possible build system and then only enhance it to support less mature systems)

And I am strugging a lot to do just this.

• I use Webpack with ts-loader and "commonjs2" as the module type. The "commonjs2" part is important to handle shared code. It works relatively ok, but far from perfect, the build is slow and Webpack has a few bug with dependencies and honestly... I am not sure what I am doing.
• I've tried Esbuild: the neutral platform won't work as-is in Next.js 12, while it should, maybe because I haven't switched to Webpack 5?
• SWC bundler doesn't seem mature enough

Would anyone volunteer to give a shot at writing a demo fullstack package that fulfill those requirements? I can provide a demo of what I've done so far with Esbuild (with Lerna, Turborepo and all 🚀)

I think having an example like this would help writing more packages for Next.js app, even if there is no plugin system yet, it shouldn't prevent people to write good old NPM package.

[eric-burel]

My current progress: https://github.com/VulcanJS/vulcan-npm/blob/main/packages/react-ui/package.json
It shows the working Webpack config, and the command I tried: using Esbuild neutral platform that produces ES modules, but it didn't import. Maybe that's due to using Webpack 4, I don't know; Then I tried using Esbuild client/server export, still not valid.

My experiments broke Next so I struggled for longer than I would admit before thinking about erasing .next and rebuilding. It kept using the initial Webpack build for some reason. Next cache doesn't badly built packages it seems.

[eric-burel]

I've started a repo here: https://github.com/VulcanJS/npm-the-right-way

• Webpack: ok but slooooow
• Esbuild: almost, somehow the package won't import in the demo Next.js app despite using v12 and ES modules
• SWC: bundler is not yet stable, waiting
• Bun: not yet ready to support Node (at the time of writing), waiting

[mxvsh]

any update on this? 😢