RFC: Deployment Adapters API

[leerob]

To ensure Next.js can be deployed anywhere, including severless platforms with custom requirements, we are planning to add deployment adapters. Vercel will use the same adapter API as every other partner.

Background

Next.js has supported self-hosting since 2016, including ejecting out of the Next.js server to a fully custom Express server. This includes deployment as a Node.js server (next start), standalone output, or a static export.

However, it has been difficult for serverless platforms like Netlify to support deploying Next.js due to their custom requirements. After talking with their team and others, we want to make Next.js easier to maintain for deployment platforms.

We also want to ensure Vercel adheres to the exact same adapter pattern, so there is parity between deployment providers for the Next.js output format used.

Pain points

After discussing with various teams from different providers and collecting their feedback, we have identified several pain points in the existing build outputs and our API surfaces.

We aim to address the following issues in this RFC:

No signal for when background work like revalidating is complete

• Currently, to track background work, one must reach into the internals and reverse engineer how the request lifecycle is being handled.
• An example of this can be seen here.

No ability to set or change specific next.config values without patching the file directly before a build

• To modify configs in next.config today, providers have to either wrap their user’s next.config manually or use internal environment variables that aren’t officially documented (related example).

No build interface for receiving configs/entrypoint information without digging through undocumented manifests

• The manifests Next.js creates today are undocumented and versioned separately from Next.js’ versioning, which can make them harder to track and rely on.
• An example of the work needed to rely on one of these manifests can be seen here.

No stable interface for executing entrypoints without the full next-server

• To successfully execute an entrypoint currently, the full next-server must be loaded and relied on. This causes pain from slowing down cold boots and giving less control over the request. Examples of handling that need to be added to leverage next-server in different environments can be seen here and here.

Proposed changes

Build output changes

To fix the core issue with executing entrypoints, we will remove the need to use next-server.

All entrypoints, including middleware, will now have a consistent signature that can be used:

// Node.js runtime
export async function handler(
  req: IncomingMessage,
  res: ServerResponse,
  ctx: { waitUntil: (promise: Promise<void>) => void }
): Promise<void>

// Edge runtime
export async function handler(
  req: Request,
  ctx: { waitUntil: (promise: Promise<void>) => void }
): Promise<Response>

Each entrypoint will now expose its signature directly, eliminating the need to load manifests during runtime. This allows each entrypoint to operate independently, loading only its required configuration.

To address concerns about knowing when background tasks are complete, a waitUntil callback can be provided. This callback will receive a promise that resolves once Next.js finishes processing tasks such as cache revalidation or executing after() callbacks.

If waitUntil is not provided, the promise returned by the handler method will not resolve until all background work is completed. For the edge runtime, this means the Response will not be returned immediately unless waitUntil is used.

Adapter API details

To alleviate two of the most significant pain points we've seen across providers—modifying next.config values and tracking outputs in the .next folder—we are implementing the following new adapter API:

interface NextAdapter {
  // "vercel", "netlify", "cloudflare" ...etc
  name: string,
  // "modifyConfig" is called before build and is an opportunity
  // to modify the loaded Next config
  modifyConfig(config: NextConfig)?: Promise<NextConfig> | NextConfig,
  // "built" is called after compilation and pre-rendering is finished
  // outputs will include all assets/functions we've created
  // it also includes public folder assets. Each pre-render path is
  // it's own function output with it's own config
  onBuildComplete({
    routes: {
      headers: Array<CustomRoute & { headers: Record<string, string> }>
      rewrites: Array<CustomRoute & { destination: string }>
      redirects: Array<CustomRoute & { destination: string, code: number }>
    },
    outputs: Array<{
      id: string,
      fallbackID?: string, // a fallbackID points to another output ID
      runtime?: 'nodejs' | 'edge',
      pathname: string,
      allowQuery?: string[]
      config: {
        // Any user provided function / pre-render config is provided here
        maxDuration?: number
        expiration?: number
        revalidate?: number
      },
      // These are the traced dependencies needed for the entry
      // to run in an isolated environment (standalone)
      // Record of file name (relative from project root) to absolute path
      assets?: Record<string, string>
      filePath: string,
      type: RouteType
    }>
  })?: Promise<void> | void
}

export type RouteHas =
  | {
      type: string
      key: string
      value?: string
    }
  | {
      type: 'host'
      key?: undefined
      value: string
    }
    
interface CustomRoute {
  source: string
  has: RouteHas[]
  missing: RouteHas[]
}

enum RouteType {
  /**
   * `PAGES` represents all the React pages that are under `pages/`.
   */
  PAGES = 'PAGES',
  /**
   * `PAGES_API` represents all the API routes under `pages/api/`.
   */
  PAGES_API = 'PAGES_API',
  /**
   * `APP_PAGE` represents all the React pages that are under `app/` with the
   * filename of `page.{j,t}s{,x}`.
   */
  APP_PAGE = 'APP_PAGE',
  /**
   * `APP_ROUTE` represents all the API routes and metadata routes that are under `app/` with the
   * filename of `route.{j,t}s{,x}`.
   */
  APP_ROUTE = 'APP_ROUTE',

  /**
   * `IMAGE` represents all the images that are generated by `next/image`.
   */
  IMAGE = 'IMAGE',
  
  /** 
   * `STATIC_FILE` represents a static file (ie /_next/static)
   */
  STATIC_FILE = 'STATIC_FILE',
  
  MIDDLEWARE = 'MIDDLEWARE',
}

Below is an example of the context provided to onBuildComplete for a minimal project.

/* Project structure:

app/
  page.tsx
  layout.tsx

middleware.ts
*/

onBuildComplete({
  routes: {
      headers: [
        // Next.js' default cache-control headers
        {
          source: '/_next/static/(.*)',
          headers: { 
            'cache-control': 'public,max-age=31536000,immutable'
          }
        },
        // user configured headers via next.config
      ],
      // user configured rewrites via next.config
      rewrites: [],
      // Next.js default redirects and user configured rewrites via next.config
      redirects: []
    },
    outputs: [
      {
        id: '1',
        fallbackID: 'fallback-1'
        runtime: 'nodejs',
        pathname: '/',
        allowQuery: []
        config: {
          revalidate: 30
        },
        // These are the traced dependencies needed for the entry
        // to run in an isolated environment (standalone)
        // Record of file name (relative from project root) to absolute path
        assets: {}
        filePath: '/Users/dev/my-app/.next/server/app/page.js',
        type: RouteType.APP_PAGE
      },
      // This is an example of a prerender fallback 
      {
        id: 'fallback-1',
        pathname: '/',
        filePath: '/Users/dev/my-app/.next/server/app/index.html',
        type: RouteType.STATIC_FILE
      },
      {
        id: 'middleware',
        runtime: 'edge',
        config: {
          matcher: []
        },
        pathname: '/',
        filePath: '/Users/dev/my-app/.next/server/middleware.js'
      },
      // This is a plain static chunk Next.js built
      {
        id: 'static-1',
        pathname: '/_next/static/chunks/app/page-34234.js',
        filePath: '/Users/dev/my-app/.next/static/chunks/app/page-34234.js',
        type: RouteType.STATIC_FILE
      },
      // "public/" folder files will be available here as well if present
    ]
})

To configure an adapter, users can install it in their package.json and specify it in the next.config file using the adapterPath option.

For platforms like Netlify or Vercel that aim to auto-configure the adapter, a default can be set using the NEXT_ADAPTER_PATH environment variable. However, any adapter explicitly configured by the user in next.config will take precedence over the one provided via the environment variable.

// next.config.ts
module.exports = {
  adpaterPath: require.resolve('@next/adapter-vercel')
}

Configured adapters are only utilized during builds to prevent conflicts in the development environment and simplify adapter implementations. If the need arises, we may explore dev-specific hooks for adapters in the future.

Adoption and rollout

We have created a working group with Netlify, Cloudflare, Amplify, and OpenNext. Together, we are designing and iterating on the API. We will begin by using the Vercel adapter to dogfood the new API.

Once these APIs reach stability, we will provide official documentation to ensure providers can fully understand and utilize them. Additionally, platforms which adhere to the adapter API will be listed in the Next.js deployment documentation.

We want to ensure the community can easily find and contribute to adapters, so we plan on hosting the repositories in the Next.js GitHub organization. We have already published a number of examples for deploying self-hosted Next.js applications here.

Not planned

We do not plan for this Adapters API to be used (or designed) for allowing custom runtimes currently.

For partners and providers

If you would like to collaborate with us on implementing an adapter, you can respond on this thread or reach out to [email protected].

[aralroca]

Good news!

[mhart]

Amazing stuff @leerob!

Questions on minimalMode because I don't see any mention of it here:

1. Will it go away, or be refactored, or be exposed and fully documented for non-Vercel platforms to use?
2. If the basic idea of it is staying, can it be refactored into separate features? It's currently one overloaded flag that's really just a proxy for "runs on Vercel" – but behind the scenes it's responsible for a number of different behaviours that other platforms do support.
3. There's a whole bunch of logic that's locked up behind that and x-matched-path, including managing optimized PPR renders with a static render from the edge, followed by a POST to the "origin" to resume the stream. This is often advertised as a core feature and benefit of using Next.js, but AFAICT there's no other way to turn this behaviour on without setting minimalMode and passing an x-matched-path header – even though the functionality itself could be done on any platform that has CDN/edge serving capabilities. Can we have this refactored out?

Basically, would love to see as many Vercel-specific flags, headers and env vars (eg, minimalMode, x-matched-path, x-now-route-matches, NEXT_MINIMAL, NEXT_PRIVATE_MINIMAL_MODE, NOW_BUILDER, NOW_REGION, etc) either documented, or ideally, refactored out into generic capabilities that any platform can implement if they support that behaviour.

Ofc totally get there'll be things y'all want to run as optimized as you can, but if there's a way that can be refactored into the adapter design, that'd be ideal! 🙏

[ijjk]

With the refactoring to the handler interfaces and each entry being able to be invoked independently without next-server anymore minimal mode effectively goes away.

We aim to get rid/replace all the above mentioned values as well with official APIs that are documented.

[mhart]

Brilliant @ijjk, thanks for the clarification

[ascorbic]

Ex-Netlifier here! Some questions purely out of curiosity: does this mean there'll be separate entrypoints for each route? If so, will this mean adapters will need to implement their own routing, redirects, rewrites, header rules etc? If so, I'm sure they would appreciate these rules being comprehensively documented and even a reference implementation. When I worked on it I remember those rules being very lightly documented (and sometimes inaccurately), and I had to do quite a lot of reverse engineering to work out the order and logic. The fragility of this was one of the reasons we switched to using standalone mode with lots of hacks, rather than trying to run the entrypoints directly.

[lucacasonato]

Very similar questions to @ascorbic - we are not keen to replace the actual singular entrypoint for Deno Deploy either with multiple entrypoints, but we are very interested in being able to hook it to be able to tightly integrate with CDN cache for example (currently x-next-cache-tags is flagged by minimal mode). Will this be something that we can do?

[ijjk]

The next-server entry will be remaining for compatibility which will still handle resolving rewrites/dynamic routes and then invoking the correct entrypoint but will be much leaner as the majority of the logic will move to the entries. The single entrypoint handling is to make more optimized deployments much easier and not have to worry about deploying all entries together.

[joseppu]

wow, didn't think this was possible. one of you guys should tweet: deployment adapters achieved internally.

[psv2522]

Good stuff

[anicolaides]

Make sure to allow for HTTP Headers customizability within each of these adapters. For instance, Cloudflare is known to cause issues with stale-while-revalidate until they support it at the CDN level, if they ever do.

[nilsingwersen]

That's great news. I've got like 3 questions.
Will you take on developing some of these adapters yourself?
Will you incorporate the work of open-next or this something completely new?
How will images work? Just use sharp and optimize on build or will there be the ability to use different image providers like cloudinary and cloudflare images?

I'm pretty stoked about this.

[damiensedgwick]

I have a question about the RouteHas type of

export type RouteHas =
  | {
      type: string
      key: string
      value?: string
    }
  | {
      type: 'host'
      key?: undefined // Why does this have an optional key of type undefined?
      value: string
    }

This feels kinda weird and I don't get it but I could also be missing something really obvious.

[ThomasAunvik]

I think the typescript isn't completely there yet, but if the type: string in the first | was had constants string, like type: 'header'.

You could do if(route.type == "host") and the linter would know based on the type that key is always undefined.

[james-elicx]

You can find some more examples for that one in the Build Output API spec - https://vercel.com/docs/build-output-api/configuration#source-route.

To answer your question, the host one wouldn't have a key as you're only comparing values, whereas other things like cookies, headers, and query params all have keys and values to compare.

[timothyis]

To answer your question, the host one wouldn't have a key as you're only comparing values

I think specifically, the question is "why is key for type: 'host' optionally applicable when the value has to be undefined?" At this point it feels like it should just be omitted.

[damiensedgwick]

I think specifically, the question is "why is key for type: 'host' optionally applicable when the value has to be undefined?" At this point it feels like it should just be omitted.

yes this

[tom-sherman]

What's the planned versioning strategy for this API? Will it follow the same semantic versioning as Next.js itself?

[ijjk]

Yes, once stable this will follow same semver as Next.js

[WINOFFRG]

Are we planning to add support to allow both SSG and ISR/SSR at the same time, to be able to get the functionality that some pages could be served from a static HTTP server and some from next server?

Reason: We have our custom go lang server which acts as a Static Gateway, Next server or Node server doesnt scale well considering when the 40% of our pages are static. In a distributed system it causes a lot of issue as we cant store tons of pages in memory, secondly EFS is quote costly, then we can store HTML strings directly in cache for obvious reason, then we dont want to waste compute for static pages.

So we planned that there must be some sort of way or load balancer which has the capability to HTTP serve static pages and dynamic serve Next pages via its own server.

[MrHamel]

Why use a custom web server, when an application load balancer with path-specific rules can direct traffic to Cloudfront/S3, or EC2/ECS/Lambda? Also, why use a custom web server at all when Nginx exists?

[OlegLustenko]

So, I hope this initiative will help to friend Docker and Nextjs ENV variables

[ijjk]

Hi, we do have experimental handling to not inline env variables already during compilation with next build --experimental-build-mode=compile then when you want to you can inline via next build --experimental-build-mode=generate.

[r34son]

@ijjk Could you document options for --experimental-build-mode?

[jotanarciso]

Great news!

[himanshuchandola]

Good news 😃

[mrlemoos]

This is great news!

[thedevopsguyblog]

Looking forward to seeing AWS Amplify integration 😎