RFC: Expose a server route manifest to allow routing requests to built environments

[serhalp]

Motivation

One of the (very few!) obstacles to creating a full-featured, self-contained, framework-agnostic Vite plugin is the lack of a Vite API surface indicating which server entry point (if any) a given request should be routed to.

Below is a proposal to introduce such information. This will allow for use cases like separate SSR/RSC entry points, arbitrary server bundle splitting logic, granular per-route rendering modes, and avoiding invoking unnecessary compute to serve 404s for unknown paths.

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 3" from the above, where there was broad ecosystem alignment on the need and the appropriateness of solving it in Vite core.

Proposal

Add a new method addRoutes to the ViteBuilder prototype (called by frameworks) and a new argument routeManifest to the buildApp hook (read by providers).

Note

Alternative name ideas: routes, routesByEnvironment

This leverages the web platform URL Pattern standard to flexibly, agnostically specify route patterns.

interface Route {
  method?: string | string[]; // omit to match any method
  pattern: URLPatternInit | URLPatternInit[];
}

interface ViteBuilder {
  /** ... existing properties like `environments`, `build()`... */

  /**
   * Register routes that the named environment is responsible for handling.
   */
  addRoutes(envName: string, routes: Route[]): void;
}

Usage examples

In a metaframework:

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

  builder: {
    // This framework may have FS routes, declarative routes, type inference,
    // generated routes, implicit RPC routes, special system routes...
    buildApp: async (builder) => {
      await builder.build(builder.environments["client"]);

      await builder.build(builder.environments["ssr"]);
      builder.addRoutes("ssr", gatherSsrRoutesSomehow());

      // In this example, Server Functions are built as an isolated environment,
      // with its own entry point
      if ("serverFunctions" in builder.environments) {
        await builder.build(builder.environments["serverFunctions"]);
        builder.addRoutes("serverFunctions", [
          {
            method: "POST",
            pattern: { pathname: "/_serverFns" },
          },
        ]);
      }

      // In this example, the framework's (global) middleware feature gets built
      // as an isolated environment, with its own entry point
      if ("middleware" in builder.environments) {
        await builder.build(builder.environments["middleware"]);
        builder.addRoutes(
          "middleware",
          // Framework userland config has its own middleware matcher format but
          // is responsible for normalizing this to method + URLPattern
          getMiddlewareConfig().matchers.map((matcher) => ({
            pattern: toURLPattern(matcher),
          })),
        );
      }
    },
  },
};

In a provider plugin:

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

    buildApp: {
      order: "post",
      async handler(
        builder,
        /**
         * Map from env name → the routes this environment is responsible for handling.
         */
        routeManifest: Record<string, Route[]>;
      ) {
        const serverEnvs = Object.values(builder.environments).filter(
          ({ consumer }) => consumer === "server",
        );
        for (const environment of serverEnvs) {
          const routes = routeManifest[environment.name] ?? [];
          // Platform-specific logic to generate workers/functions/servers that will
          // handle requests matching any of `routes[].{method,pattern}`
          await createServerlessFunction({
            name: environment.name,
            // Separate challenge — see "need 1" in https://github.com/vitejs/vite/discussions/20907
            entrypointFile: "fixme",
            // Platform has its own route matching format but is responsible for
            // normalizing this from method + URLPattern
            paths: fromURLPattern(routes),
          });
        }
      },
    },
  };
}

Discussion

Assumptions

The proposal above introduces the assumption that a Vite Environment has zero or one server entry point. As such, it encodes no direct relationship between requests and server entry points. Rather, a request is routed to one or more Environments (for example, a middleware environment and an SSR environment), each of which has an entry point.

This seems like a reasonable invariant to impose, because:

• By design, Environments are assumed to be isolated (i.e. no shared state, memory, globals, etc.). It seems reasonable to also assume that two separate server entry points may be (but are not necessarily) isolated.
• Two or more server entry points that may otherwise have shared an Environment can always instead be split up into one Environment each (right?). If they are not independent, dependencies can be encoded at the framework or plugin level.
• Many Environment API implementations have already been naturally gravitating toward this model. For example, React Router 7's serverBundles option results in one Environment per server bundle.

Alternatives considered

Leverage the configResolved hook

This is too early in the lifecycle for many metaframeworks to have resolved the necessary information, which may be a byproduct of a full app build.

Leverage writeBundle and/or generateBundle hooks

As I understand it, Vite avoids extending Rollup types by design.

Attach route manifest to Environment instances

this.environment is already available to plugin build hooks, making this appealing.

But this felt smelly to me, as the app's server route manifest is not an inherent property of a given environment, but rather a property of the built app that happens to be data keyed by Environments.

---

Shout out to @jamesopstad for inspiring some of this here

[serhalp]

A question I have about my own proposal: if I'm authoring a provider plugin (let's say @netlify/vite-plugin) and I'm intending (this is the whole point!) for it to have no knowledge of specific metaframeworks, how can I know whether the user's metaframework plugin has called addRoutes() to register any routes (i.e. it's compatible)?

Maybe this is the one part where the solution to "need 1" intersects with this? By having, let's say, an explicit way to identify a Environment's server entry point (there is zero or one, remember), one can formulate the invariant that a server Environment with a server entry point must have at least one route in the manifest, and server Environments with no server entry points can be safely ignored by the provider plugin at build time.

🤔

[matthewp]

I find this all very confusing (I'm a maintainer on Astro). Vite has nothing to do with routing in production. Adding routing things just for dev creates dev/prod differences and those are never good. I'm probably missing something and would like to understand better. Is this for stuff that's only relevant in dev?

[matthewp]

I talked to some people offline and understand just a little better. I still have some concerns / questions.

• It's unclear when a vite plugin should use this information. In the other proposal it shows it being used in writeBundle. This hook gets called for each environment build, but you would only want to use it after the last environment build.
• Astro does not use the Vite CLI and therefore doesn't use buildApp. I'd like to see this API explains in terms of the programmatic Vite builder API.