Next.js Adapters: Build Once, Deploy Everywhere

Hello, React Summit. I'm very excited to be here today to talk about Next.js adapters. And this has been our effort over the last few months to make Next.js more open and deployable wherever you want to deploy it.

So to start, I'm JJ Casper. I've been at Vercel for the past six years now, working on mostly Next.js. I absolutely love open source and everything we can do with it. And I'm excited to see how much further we can take it.

All right. So a quick overview. We had gone through a lot of history with deploying Next.js. Way back in the beginning, we had mostly just Node servers. So we had Docker environments, we had now v1 if you've been along for the journey that long. And then we tried to move into this new world of serverless. But putting a whole entire Node server inside of a serverless function wasn't super easy.

So we tried to figure out how to do that. And we came up with this target serverless mode. And it basically tried to bundle all of your code into these as small as possible bundles. But we ran into some issues with that, which mostly came down to native modules and trying to read from the file system and things like that. So we were like, OK, what's next? And then we tried this mix mode, which we called output stand alone for the most part. And that one tried to do a mix of bundling as much as it could, but also tracing the files it couldn't bundle so that you could create a zip file with everything you needed and still be as optimized as possible.

But there's still some shortcomings with that, because you still need a server to resolve the route URL to an entry point and load it with all that logic. So we tried to take the next evolution for adapters. Going back to the deployment challenges, most platforms have very specific handling. Netlify, Vercel, CloudFlare, all have different ways of handling primitives. A Node server alone can't be optimized for each platform as much as needed. Next.js documentation covers reading from the .next folder, but variations exist, leading to reverse engineering needs.

Introducing adapters simplifies this complexity. With adapters, you write your Next.js app as usual, while a separate adapter layer handles optimization for the specific provider. Users can create custom adapters for unique needs. The adapter interface focuses on minimalism to avoid unnecessary complexity. It includes essential hooks like naming the adapter, modifying configurations based on the environment, and providing structured outputs for effective handling of manifest entries, static files, and middleware.

The adaptability of the adapter interface allows for seamless optimization and control. Each adapter can be named for clarity, such as Netlify or Vercel. Customizing configurations based on the environment becomes easier with the modify config hook. The onBuiltComplete feature offers structured output for easy handling of various elements, eliminating the need for reverse engineering. This structured approach ensures compatibility and ease of use in different deployment scenarios.

So this is the adapter interface we came up with. We wanted to keep it as minimal as possible so that we don't give too many hooks to cause issues. But at the same time, give the right amount of hooks. You can optimize it and control it as much as you need to. So we have a name so you know which adapter you're using. So this might be Netlify, Docker, or Vercel, et cetera. And then we have a modify config. So talking with a bunch of providers, we saw the need to customize your config based on the environment you're in. So you might need to toggle custom end variables or stuff like that. And then onBuiltComplete. This is the most magic we provided, which gives you a structured output of all the manifest entries, all the output, all the static files, middleware. And it lets you handle them as you need. And this will be covered by SemVer. So there's no need to reverse engineer. There's no issues from that. And it can be platform-specific optimizations. And it's just much more structured, much safer.

And then this gives you a type interface for this adapter. And it's just two hooks. And we hope that this is all that's needed. And as we iterate with our partners and ourselves, we will iterate on this API and stabilize it and also document it. So this is that modified config hook we talked about, which gives you the existing config we loaded and lets you modify and return whatever you need to change. And then the onBuiltComplete, which gives you all the routes we generated for your headers, your rewrites, your redirects. And then the outputs, which is the bulk of it. And then one of the biggest lifts of this change was basically we had to refactor our next server interface to basically allow each entry point to handle its own responses. And this allows it to be much more optimized, because you can deploy each entry point to its own function or its own server. And it doesn't have to all be coupled together in a monolithic faction. And this gives you better cold start performance and it allows you to scale much easier and it's just much more flexible. But this was kind of a hidden effort under the adapter change, because it's not a config. It was basically refactoring of the underlying code base.

And it was really fun getting to work with all the partners. So Netlify, CloudFlare, OpenNext, and Amplify. They all jumped into the channel and chimed with their feedback from issues they had with deploying. And it was great, because we all can make our experiences better together, and I love that. And we identified API that we even had pain points, and we were like, oh, we can solve them together.

So following on with adapters, a long requested thing was documentation on how to deploy Next.js in various environments in different ways. And this will be coming as we stabilize this interface. And we're going to be testing with the partners, of course, and we'll be tweaking things as needed before we stabilize it. And we'll be having some beta releases and just lots of dogfooding. And then the GA. So all our partners will be releasing together, hopefully.

Overview of the benefits. So we have simplified deployments. You no longer have to reverse engineer anything. It should be platform-agnostic. You should just write your Next.js app and not have to worry about if it's going to break on this platform or in Docker or anywhere like that. And then hopefully we have optimized resources. Like you shouldn't have to worry about cold boots slowing down your application, because you're loading routes that maybe will never be requested. And just overall, better developer experience, which we all love. And yeah. Build once, deploy everywhere, and optimize automatically from your provider.