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.

🤔

[magne4000]

I think "need 1" is the real blocker we have to address. For example, looking at a few existing projects:

• TanStack Start sets environments.ssr.build.rollupOptions.input.index
• Cloudflare’s Vite plugin also sets environments.ssr.build.rollupOptions.input.index
• Nitro treats any defined environments.ssr.build.rollupOptions.input as a fetch-server entry
• Photon behaves like Nitro, but requires an explicit flag set to true

The problem is that if TanStack Start and the Cloudflare Vite plugin are both installed, we can’t reliably use rollupOptions to determine the server entry, because it may just point to Cloudflare’s entry instead. In that setup, configResolved will always end up with rollupOptions.input pointing at the Cloudflare entry. So if we need access to the actual TanStack Start server entry, the only current option is this pretty fragile extraction from the config hook.

[jamesopstad]

The problem is that if TanStack Start and the Cloudflare Vite plugin are both installed, we can’t reliably use rollupOptions to determine the server entry, because it may just point to Cloudflare’s entry instead.

@magne4000 Can you explain a little more about why you want to access the TanStack Start server entry in this scenario? I would consider the Cloudflare entry to be the server entry.

[magne4000]

In certain scenario, Photon can inject a virtual module between the user entry and Cloudflare (or any other target) for instance, or apply code transformation on the user entry.
This also allows consistent application of patterns like side-effect injection.
Any tool that would like to transform the user entry must be able to do it consistently IMO.

[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.

[jamesopstad]

My first question is still the more important one, how does a plugin know when the build code is "done" and they can use the route data?

I think this would have to be based on a convention that frameworks use buildApp without an order and platforms use the buildApp hook with order: 'post'. This is how it is in @serhalp's examples.

[matthewp]

writeBundle gets called for every environment build, right? There are N possible environment builds. Isn't his example creating new manifest file N times then (a possibly expensive operation)?

[jamesopstad]

I think the examples in this discussion supersede the previous examples that used writeBundle. buildApp is much better suited to these kinds of scenarios.

[matthewp]

Ok, thanks for the clarification.

In that case I would suggest a different hook for the different use-case, like how there is a writeBundle and generateBundle hook.

I'd be curious if there are use-cases for separate buildApp configs in the same project. I guess it would be if a user was using multiple framework plugins?

[jamesopstad]

I'd be curious if there are use-cases for separate buildApp configs in the same project. I guess it would be if a user was using multiple framework plugins?

We have a use case in the Cloudflare plugin. Typically, a framework defines its own buildApp function to build the environments it is interested in. By defining a buildApp hook, we can build additional Worker environments that the framework is not concerned with. The user can call these Workers via service bindings. The buildApp hook (with order: 'post') is also a good place for platform plugins to put any other code that needs to run at the end of the build. We haven't fully moved to this approach yet because we still support Vite 6 but we'll be adopting it more.

[jamesopstad]

Nice proposal @serhalp! My main concern is that this makes routing a purely build time concern. I feel that environments should be consistent across dev and build and so the routing info will also be needed in dev.

[magne4000]

Hey everyone! 👋

I've been working on finding the most minimal API possible to address point 1 (server entry point location) and point 3 (routing metadata).

The core question we're trying to solve is:

How can deployment targets (Netlify, Cloudflare, Node, etc.) discover and work with the various server entries that frameworks define?

Proposal

The approach I landed on is pretty straightforward: use a shared global store object.

// This package exports a global `store` object
import { store } from "@universal-deploy/store";

/* The store is minimal. It's essentially just this:
const store = globalThis[Symbol.for("ud:store")] ||= { entries: [] };
*/

// Registering entries is as simple as pushing to the store
store.entries.push(
  {
    id: "awesome-framework/standalone",
    pattern: "/standalone",
  },
  {
    id: "./src/server/api.ts",
    pattern: "/api",
  },
);

// Each entry follows this type:
export interface EntryMeta {
  /**
   * Module identifier for this entry. This can be a filesystem path or a virtual module.
   */
  id: string;
  /**
   * HTTP method(s) to match. When omitted, matches all HTTP methods.
   */
  method?: HttpMethod | HttpMethod[];
  /**
   * Route pattern(s) to match for this entry.
   *
   * Uses the {@link https://developer.mozilla.org/en-US/docs/Web/API/URLPattern | URLPattern API} syntax.
   */
  pattern: URLPatternInput | URLPatternInput[];
  /**
   * The Vite environment for this entry.
   *
   * @default ssr
   */
  environment?: string;
}

Note

This proposal isn't set in stone. The main goal here is to show that we can keep things really minimal.

Proof of Concept

We've built a working POC called universal-deploy. Check out the repo for all the details. On a high-level, here's what it includes:

• Global Store: Register server entries via @universal-deploy/store
• Universal Routing: Built on the URLPattern standard temporarily uses rou3 for simplicity
• Minimal conventions: Easy for any Vite-based framework to adopt
• Vite plugins that provide common functionality:
  • compat: Auto-registers SSR rollup entries for frameworks that haven't adopted universal-deploy yet
  • catchAll: Aggregates and routes all store entries behind a single entry point
  • devServer: Handles routing to store entries during development
• Adapters: Temporary adapter for Netlify (we can remove this adapter after @netlify/vite-plugin adopts the proposal), and an adapter for Node (can be built into frameworks). Note that @cloudflare/vite-plugin works out of the box, and vite-plugin-vercel@beta alreayd uses @universal-deploy/store — they already work without any adapters.

Usage

For framework authors

Just call store.entries.push anywhere in your plugin, ideally before the configResolved hook:

import { store } from "@universal-deploy/store";

export function awesomeFramework(): Plugin[] {
  return [
    {
      name: "awesome-framework",
      config() {      
        store.entries.push(
          {
            id: "./src/server/api.ts",
            pattern: "/api",
          },
          {
            id: "awesome-framework/ssr",
            pattern: "/**",
          },
        );
      },
    },
  ];
}

For deployment plugin authors

If the deployment provider needs a single server entry, the easiest approach is to set rollupOptions.input to catchAllEntry. The catchAll plugin will handle resolution:

import { catchAllEntry } from "@universal-deploy/store";

export function awesomeProvider(): Plugin[] {
  return [
    {
      name: "awesome-provider",
      enforce: "post",
      configEnvironment: {
        // Give other plugins time to declare their entries
        order: "post",
        handler(name, env) {
          if (env.consumer !== "server" && name !== "ssr") return;

          return {
            build: {
              rollupOptions: {
                input: {
                  // `virtual:ud:catch-all`
                  index: catchAllEntry,
                },
              },
            },
          };
        },
      },
    },
  ];
}

If the deployment provider supports multiple server entries, read store.entries in a post configEnvironment hook and configure rollupOptions.input:

import { store } from "@universal-deploy/store";

export function awesomeProvider(): Plugin[] {
  return [
    {
      name: "awesome-provider",
      enforce: "post",
      configEnvironment: {
        // Give other plugins time to declare their entries
        order: "post",
        handler(name, env) {
          if (env.consumer !== "server" && name !== "ssr") return;

          return {
            build: {
              rollupOptions: {
                input: Object.fromEntries(
                  // Map entries to their destinations
                  store.entries.map((e) => [
                    entryDestination(e),
                    e.id,
                  ]),
                ),
              },
            },
          };
        },
      },
    },
  ];
}

Note

Alternatively to rollupOptions.input, you can use this.emitFile at later stages if that works better for your use case.

Addressing Concerns

"Pushing entries before configResolved is too early for many frameworks"

So first, let's ask: how many frameworks actually lack information about their server entry points before configResolved?

My gut feeling is that frameworks with code splitting support already have this information available early on—think Nitro-based frameworks, for example. For other frameworks, they could use a single virtual server entry, which helps decouple the build config from the actual entry point.

Now, if this turns out to be a legitimate concern and we find frameworks that genuinely need the entire build process to complete before they can determine their server entries, we could use something like this:

// Framework side
export default {
  name: "awesome-framework",

  builder: {
    async buildApp(builder) {
      // Let's say the framework builds these environments
      await builder.build(builder.environments.client);
      await builder.build(builder.environments.ssr);
      // At this point, `store.entries` is fully populated
    },
  },
};

// Provider side
export function awesomeProviderPlugin({ environment }: { environment?: string }) {
  return {
    name: "awesome-provider",

    builder: {
      buildApp: {
        order: "post",
        async handler(builder) {
          // Frameworks should be built by now, and most importantly, `store.entries` should be populated
          const providerEnv = builder.environments[environment ?? "ssr"];
          if (
            // Don't rebuild an already-built environment...
            !providerEnv.isBuilt
            // ...unless we're dealing with one of these frameworks
            // In that case, trigger a second build
            // TBD: extract this from `providerEnv.config` or similar
            || shouldRebuildServerWithGlobalStore
          ) {
            await builder.build(providerEnv);
          }
        },
      },
    },
  };
}

If you know of any specific frameworks that work this way, let me know. We can add them to the POC so we can test out a proper solution.

What's Next?

Let me know what you think!

After we get some feedback, the next step would be finalizing the API.