RFC: annotate server environment request entrypoints

[serhalp]

Motivation

In order to generate the necessary deployment configuration, a platform provider plugin (e.g. Netlify, Cloudflare, Vercel, etc.) must know where to find files that contain the framework’s request handler (in this document I’ll refer to this file as a server request entrypoint).

In the current n·m world, a framework-specific, provider-specific adapter either has programmatic access to this information via its framework-specific adapter interface (for example, see Astro), or it has documented knowledge of this from the framework. This isn't possible in a framework-agnostic plugin.

What I've seen around the ecosystem is reading config.build.rollupOptions.input during the ssr build or hoping there's one bundle element with type === "chunk" && isEntry in the generateBundle hook. This leaky assumption that a bundle entry chunk happens to be a server request entrypoint may hold for some frameworks in some cases, but not all. rollupOptions.input can reference multiple bundle entries, some or all of which may not be request entrypoints.

In addition, in order to do anything useful with the file, a provider plugin must know how to invoke its request handler and understand the semantics of its responses. In the current n·m world, a framework-specific, provider-specific adapter has documented knowledge of this from the framework (for example, see React Router 7). Each is different, although in the last year or so the ecosystem has been coalescing around the Fetchable interface.

Note

For a much more detailed deep dive into the motivation for this, see #20907. I'll keep it concise here.

This RFC is a concrete proposal to address "need 1" and "need 2" from the above, where there was broad ecosystem alignment on the need and the appropriateness of solving it in Vite core (vitejs/ecosystem#3).

Proposal

// @see https://fetchable.org/
type RequestEntrypointType = 'fetchable' | 'custom'

interface RequestEntrypointOptions {
  type?: RequestEntrypointType
}

interface EnvironmentOptions {
  // keys are Rollup input names
  requestEntrypoints: Record<string, RequestEntrypointOptions>
  /* ... existing fields... */
}

interface ResolvedRequestEntrypoint {
  name: string // stable entrypoint name (= Rollup input name)
  type: RequestEntrypointType // defaulted to fetchable
}

interface RequestEntrypointOutput extends ResolvedRequestEntrypoint {
  fileName: string // emitted file for this input
  chunk: OutputChunk // if needed
}

class Environment {
  getRequestEntrypoints(): ResolvedRequestEntrypoint[]
  getRequestEntrypointOutputs(bundle: OutputBundle): RequestEntrypointOutput[]
  /* ... existing fields... */
}

Server bundle inputs that are request entrypoint files should be specified as such under requestEntrypoints. These are implied to be Fetchable modules, unless specified otherwise with type: 'custom'.

Including a key in requestEntrypoints that has no matching entry in (normalized) rollupOptions.input results in an error.

Usage examples

In a metaframework:

export default {
  name: "cool-framework",
  /* ... */

  config() {
    return {
      /* ... */
      environments: {
        coolBackend: {
          consumer: 'server',
          build: {
            rollupOptions: {
              input: {
                ssr: 'virtual:cool-framework/app-entry',
                rsc: 'virtual:cool-framework/rsc-entry',
                api: 'virtual:cool-framework/api-entry',
              },
            },
          },
          requestEntrypoints: {
            ssr: { type: 'fetchable' },
            /* note rsc is not a request entrypoint, thus not listed here */
            api: {}, // fetchable by default as well
          },
        },
      },
    },
  },
}

In a provider plugin:

export function nicePlatform(): Plugin {
  return {
    name: "nice-platform",
    /* ... */

    applyToEnvironment(environment) {
      return environment.config.consumer === 'server'
    },
    generateBundle(_, bundle) {
      const requestEntrypointOutputs = this.environment.getRequestEntrypointOutputs(bundle)

      for (const entrypoint of requestEntrypointOutputs) {
        if (entrypoint.type === 'fetchable') {
          // Platform-specific logic to generate workers/functions/servers that will
          // handle requests
          generateNiceServerlessFunction({
            name: entrypoint.name,
            fetchableEntrypoint: entrypoint.fileName,
            // Separate challenge — see "need 3" in https://github.com/vitejs/vite/discussions/20907
            paths: '/*',
          })
        } else console.error('Only fetchable server entrypoints are supported')
      }
    },
  };
}

Discussion

• Assumption: A request entrypoint is only relevant/useful for consumer === 'server' environments.
• Assumption: A request entrypoint is only valid if it corresponds to a rollup/rolldown input names. (Would a manually written, unbundled entrypoint file ever be needed in this context?)
• Assumption: Vite never extends rollup/rolldown types, so this can't be a new field on any rollup api layer.
• This API does not indicate which requests go to which entrypoint. That is out of scope here, although this design intentionally avoids blocking that extension. See RFC: Expose a server route manifest to allow routing requests to built environments #21212.
• The custom type is intentionally opaque. The idea is this elevates the Fetchable convention as the standard signature (our solution to "need 2" here), while generally solving for "need 1" across arbitrary signatures.
• The foo: {} shape may look weird but (1) this RFC suggests supporting an array form ['foo'], and (2) this leaves the API open for extension, particularly for the immediate needs of RFC: Expose a server route manifest to allow routing requests to built environments #21212.
• See also a bit of discussion here.

[jamesopstad]

This generally looks good to me.

Assumption: Vite never extends rollup/rolldown types, so this can't be a new field on any rollup api layer.

There are exceptions to this and I think it's OK for Vite to use a superset of the Rolldown/Rollup API. Might be worth also considering what this would look like if it was included directly in input with each value being an object. Not sure if that would be better or not.

[magne4000]

Assumption: A request entrypoint is only valid if it corresponds to a rollup/rolldown input names. (Would a manually written, unbundled entrypoint file ever be needed in this context?)

👍 I think that's a good assumption, it makes the contract between frameworks and platforms providers easier to understand.

The custom type is intentionally opaque. The idea is this elevates the Fetchable convention as the standard signature (our solution to #20907), while generally solving for "need 1" across arbitrary signatures.

universal-deploy was built on the remains of photon, which was making the same distinction between fetchable and custom.
It was really complex to maintain from end to end, and I think most adapters will just not implement anything other than fetchable.
What I ended up doing instead for universal-deploy was to extend the fetchable type with optional node capabilities, e.g.

// pseudo code
export default {
  fetch() { ... },
  node: {
    port: 3000,
    // Node adapter can use this if it exists instead of wrapping the `fetch` handler
    handler(req, res) { ... }
  }
}

This still respect the fetchable interface, but also provides extensibility.

generateBundle(_, bundle) {
...
},

I like this approach, as we can still call this.emitFile for this hook

[serhalp]

I submitted a PR for this here: #22680