RFC: Paving a path from 𝑂(n·m) to 𝑂(n) Vite deployment target plugins

[serhalp]

TL;DR

Each web deployment provider currently requires a unique, ad hoc integration layer for each meta-framework it intends to support.

Does it have to be this way? Could Vite be the bridge, allowing for a single plugin per provider to just work?

This document discusses how we got here, solutions attempted in the past, what’s changed since, the few remaining technical challenges to solve, and starts riffing on some potential solutions.

Solving this would benefit developers by offering more deployment options for their favourite frameworks and more framework options for their favourite deployment platforms. Framework maintainers and deployment providers would also benefit from reduced maintenance and landing near-universal support at once when they land changes.

Context

The N×M Problem

Currently, each framework requires an adapter for each deployment platform, as illustrated by this spaghetti:

Supporting 10 Vite-powered frameworks on Netlify requires 10 adapters. Each provider requires its own 10 adapters. Here, we see 10x4=40 adapters for 4 providers.

Each provider currently maintains—in collaboration with the framework maintainers and the OSS community—largely duplicative adapters for Astro, Remix, React Router, Hydrogen, SvelteKit, Nuxt, TanStack Start, SolidStart, Analog, Qwik, and more.

This maintenance burden comes at an opportunity cost for providers and framework maintainers, who could focus those efforts on shipping end-user-facing improvements instead.

This also has a tendency to leave smaller frameworks behind. Many adapters are under-maintained and, in reality, most of the 40 adapters in the diagram above simply do not exist.

This fragmentation may have been inevitable just a few years ago, but the ecosystem has since rapidly rallied around Vite as bundler and dev server: all ten of the frameworks Iisted above use Vite—and the dominoes continue to fall. This, coupled with the opportunities unlocked by the Vite Environment API, leads to this question:

Does it still have to be this way?

Given Vite as unifying dev server, front-end meta-framework toolkit, client bundler, and server bundler (and much more…), might it also act as the unifying bridge that would decouple providers from full-stack frameworks (and vice versa)?

Could each deployment provider maintain a single, agnostic Vite plugin?

Supporting 10 Vite-powered frameworks on Netlify should require one single agnostic Vite adapter. Each provider should require its own single adapter. Here, we see 1x4=4 adapters instead of 40 previously.

I’m vaguely aware that Cloudflare has started working on this (or something like it) and that they have an initial version working in some capacity with React Router 7 and TanStack Start. We (Netlify) have started discussing this with @tannerlinsley and other framework maintainers, and we recently soft-launched a TanStack Start Vite plugin that doesn’t actually contain any TanStack Start-specific code. I’m creating this RFC as an effort to consolidate our efforts across the ecosystem and collaborate together on solving identified challenges at their root wherever possible.

What does it take to deploy a full-stack web app?

Let’s step back.

Fully static sites (SSG) are easy: the provider just needs to know what directory to publish as static files.

When frameworks allow first-class configuration of static redirects and response headers, these must be translated into a provider-specific configuration files at build time.

Once servers are involved (SSR, API routes, RSCs, etc.), it gets hairier.

The provider must:

• before server build begins:
  • instruct the bundler to conform its server build output to a given target platform, architecture, runtime, configure externalized dependencies, etc.
• after the server build is complete:
  • identify the server bundle entries, their locations, their signatures, and their routing metadata
  • given the above entries, generate provider-specific files that will provision appropriate compute (i.e. servers, serverless functions, edge functions) that routes requests to the intended entry with the necessary signature

That about covers it. (To keep this focused, I’ll ignore local development—which is the main focus of the ongoing Vite Environment API work—and focus only on building for production.)

Scope

This can get quite muddled, so I’m going to propose some guidelines as a starting point:

1. Given a framework that follows the (Vite-endorsed AFAICT) “framework-as-Vite-plugin” approach, it should be tractable for a provider’s framework-agnostic Vite plugin to deploy apps—without requiring end users to write additional code or configuration.
2. Given a framework that follows the classic approach (providing its own CLI and/or config and/or adapter mechanism), it should be tractable for a provider’s framework adapter to delegate the app’s preparation for deployment to its framework-agnostic Vite plugin.
3. In scope for Vite: Features and functionality involved in the framework fulfilling requests; for example, SSR pages, middleware, RSC, framework-defined API endpoints, Server Functions.
4. Out of scope for Vite: Everything else; for example, static redirects, static response headers, image optimization, version skew protection, etc. These belong in some combination of framework configuration, provider configuration, and provider plugin/adapter configuration.

If you disagree with these, stop reading here and let’s discuss this first!

Needs

Through some research, discussions, and experimentation, we’ve identified some challenges to making this a reality today. I’ll discuss each separately.

1. Server entry point location

In order to generate the necessary deployment configuration, a provider plugin must know where to find the file that contains the framework’s request handler (in this document I’ll refer to this file as the server entry point).

(See also need 3.1 below for a further complexity regarding multiple server entry points.)

In the current n·m world, a framework-specific, provider-specific adapter either has programmatic access via its framework-specific adapter interface (for example, see Astro), or it has documented knowledge of this from the framework.

In some cases I’ve seen, config.build.rollupOptions.input during the ssr build (or the one bundle element with type === "chunk" && isEntry) is assumed to be that file. This leaky assumption that a bundle entry happens to be a server entry point 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 server entry points. In theory, a server entry point could even not be configured as a bundle entry at all.

It also isn’t clear how this would work given multiple consumer === "server" Vite Environments (e.g. SSR and RSC).

2. Server entry point signature

In order to generate the necessary deployment configuration, a provider plugin must know how to invoke the framework’s request handler and understands 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).

3. Routing metadata

Information about user-configured routes is needed at deployment time for several reasons:

1. Split server bundles: Some frameworks support end-user configuration of server bundle splitting behaviour, i.e. how many server entry points should be generated and which one a given request should be routed to; for example, see Remix v2. As another example, consider the in-progress Vite-native RSC plugin: as I understand it, all requests are intended to be routed to the rsc server entry point and none to the ssr server entry point directly, but there is no available mechanism for an agnostic Vite provider plugin to know this.
2. Granular rendering modes: Some frameworks support individual routes opting into different rendering modes, most notably pre-rendering (for example, see SvelteKit). Even though this happens to work on most platforms (to my knowledge) due to static assets taking precedence over (or ”shadowing”) compute, this is a leaky assumption; and it results in unnecessarily bloated server bundles besides.
3. Edge middleware: Some frameworks can be configured to build middleware separately from the main SSR handler, with an expectation that this be deployed to the edge. Such a server entry point must be identifiable, along with its intended matching routes.
4. Avoiding compute for unexpected 404s: Unless a catch-all route or dynamic 404 handler is explicitly configured, unknown paths should not require a handler invocation just to serve a static 404 response; otherwise, costs and performance suffer. To achieve this, only requests to known routes must be routed to handlers.

In the current n·m world, a framework-specific, provider-specific adapter either has programmatic access to routing metadata via its framework-specific adapter interface (for example, see Astro), or it hardcodes assumptions that there is a single server entry point and that all un-shadowed requests can be routed to it.

4. Static redirects and headers

Some frameworks support configuration of static redirects and static response headers (for example, see Nuxt). Providers must translate these into provider-specific configuration at deployment time.

In the current n·m world, a framework-specific, provider-specific adapter has programmatic access to this configuration via its framework-specific adapter interface.

Proposal

Solution

1. Server entry point location

I saw the proposed(?) environment.config.entryPoint buried in this other RFC. That seems like a step in this direction, but it still assumes a single server entry point per environment.

Perhaps output entry chunks could have an isServerEntry: boolean property?

See solution to need 3 below, which may cover need 1 as well.

Note that, as of very recently, TanStack Start and Cloudflare are experimenting with a conventional server-entry export; but it isn’t clear how this would help with a metaframework-agnostic provider plugin. This expects the end user to hook up the entry point, or for this to be done in provider templates, neither of which is (IMO) ideal DX.

2. Server entry point signature

A signature inspired by the Service Worker Web API has been gaining steam across similar realms: among many others, Cloudflare Workers, Bun, Deno, srvx, and now Vercel support this module interface:

export default {
  fetch(request: Request): Response | Promise<Response>
}

As far as I can tell, this is not documented as a standard and the community has not yet even rallied around a single name for this; we’ve sort of aligned on “fetch handler” as a name for the handler function, but nothing yet for the above.

Much like Thenables are minimally defined by simply having a .then method of a certain type, I propose we name this a Fetchable, defined as a module having a default export that is an object having a property fetch that is a function accepting a fetch Request and returning a fetch Response or a promise of one; additional named exports are allowed, as are additional properties on the default export object.

I’m not quite sure what I’m proposing concretely here, since Vite core wouldn’t really know about this at all. Perhaps this convention could be documented in the Vite SSR docs? Or perhaps output chunks could have an isFetchableEntry: boolean? Or maybe Environment instances could have supportsFetchableEntry: boolean? serverEntryType?: undefined | 'fetchable'?

I found some highly relevant past comments but in a dev context:

• Code snippets here assume this server entry point signature
• @sheremet-va says he assumes this is what a server entry point is
• @hi-ogawa brings up the possibility of defining this convention on the Vite side

3. Routing metadata

Important

Update (2025-12-04): I've written up a concrete, self-contained RFC for this here: #21212.

The goal is for a deployment provider’s Vite plugin to have some sort of access to route information at build time in environment.consumer === 'server' environments, handed off by metaframeworks somehow. This simplified pseudocode illustrates the general idea:

let routeManifest

return {
  name: 'vite-plugin-coolcloudco:build',
  apply: 'build',
  applyToEnvironment(environment) {
    return environment.config.consumer === 'server'
  },
  async writeBundle(options) {
    // NEW:
    const { routeManifest } = options
    // Map Vite route manifest format to our provider routing config format
    for (const route of getCoolCloudCoGlobsFromViteRoutes(routeManifest)) {
      // Write config to provision e.g. serverless function that runs on certain paths
      await writeFile(
        join('.ccc', 'fns', name),
        createCoolCloudCoFunctionManifest({
          entrypointPath: route.entrypointPath,
          paths: route.paths,
          excludedPaths: route.excludedPaths,
          // ? runAtEdge: boolean
        }),
      )
    }
  },
  /* ... */
}

The format used to describe routes and route matching conditions would need to cover the union of all possible requirements across SSR-enabled metaframeworks.

I’m not aware of an existing standard interchange format for this, but it could possibly build upon the URL Pattern API and perhaps the proposed URLPatternList. (I know the Remix folks are also working on something possibly relevant?) It might be interesting to pursue drafting a standard, but this isn’t necessary.

💡 It’s possible some solutions here may also serve as a sufficient solution to need 1 above: the route manifest could serve as the source of truth for server entry points and their paths, and an omitted server bundle entry would indicate that it is not a server entry point. Similarly, it may serve as a solution to need 4: redirects may easily be argued to be routing information, although response headers not so much.

4. Static redirects and headers

There are arguments to be made to consider this need in scope or out of scope for Vite. I propose that these remain out of scope; although as called out above, it may be reasonable to include redirects in routing metadata and consider only headers out of scope.

Frameworks that want to support to support this will have a few options:

1. Continue to rely on their own adapter/integration/plugin layer (i.e. remain in the 𝑂(n·m) paradigm) having access to this configuration in each provider-specific adapter
2. Leak knowledge of deployment providers and always generate known provider-specific configuration files (e.g. Cloudflare and Netlify support the same _redirects and _headers formats)
3. Steer users toward direct platform configuration (for example, SvelteKit documents this approach for Netlify)

Alternatives considered

Nitro

Nitro was extracted from Nuxt as an attempt to solve roughly the same problem as this RFC.

It was started at a different time—before the rise to near-ubiquity of Vite and before the Vite Environment API was dreamt up. Its architecture requires that metaframeworks adopt it as their server engine layer, which no existing frameworks have done so far.

Although Nitro v3 will become a Vite plugin based on the Vite Environment API, installed directly by end developers, challenges remain:

• Nitro’s approach is to shift the ecosystem from 𝑂(n·m) even further to 𝑂(1). This puts control in the hands of a single team.
• Nitro’s architecture results in all code required to support all providers in a single package. This bloats the package, slows installation, and couples providers’ releases to one another (in turn requiring an additional layer of per-provider versioning to avoid SemVer messiness). This would all result in less than ideal DX for end developers.
• Regardless, for Nitro to be successful as a Vite plugin it needs to solve or work around many of the same issues as described in this RFC.

Leveraging Vite as the foundation instead is, at the very least, worth exploring.

Vike

Vike (formerly vite-plugin-ssr) and Vike Server are also worth calling out. I’m not deeply familiar with these efforts, but as far as I understand it provides an alternative to metaframeworks, rather than a solution to decoupling their preparation for deployment from deployment providers. I believe it also has ambitions similar to Nitro, with a similar approach requiring metaframeworks to adopt it, none of which have.

The same team has also started working on extracting this layer from Vike as Photon and, further below that, https://universal-middleware.dev/. Peek at the universal-middleware source and you’ll see it’s consolidating (part of) the 𝑂(n·m) complexity into one codebase, not simplifying it.

Don’t do any of this

We could do none of this. There’s certainly an argument to be made that granular request routing information is not a concern that belongs in Vite core.

Providers could instead do one (or some combination of) the following:

• Continue to live with the 𝑂(n·m) situation we have today and contend with the resulting challenges described above.
• Perhaps, implement the proposed single Vite plugin anyway, with support for most use cases, but with a multitude of caveats for developers (likely including necessary end-user configuration beyond installing the provider’s Vite plugin), a couple entirely unsupported metaframeworks, and a number of brittle workarounds in the implementation making leaky assumptions about known metaframeworks.

[serhalp]

I know this is a bit of a meandering, fuzzy RFC. My hope is to use this as a starting point and evolve it as folks chime in and collaborate.

👋🏼 FYI I'll be at ViteConf this week, including all the evening events. Happy to discuss this with anyone!

[sapphi-red]

Hi, @serhalp 👋

I definitely want to reduce the complexity from 𝑂(n·m) to 𝑂(n), and that's one of the subgoals of the Env API. The original idea was that a runtime provider would offer an Environment Factory, which the framework would then consume.
The current Env API mainly focuses on the dev side, but the build side are also in scope. However, as you pointed out, there are indeed challenges in that direction, and due to time constraints, we haven't been able to invest sufficient effort there yet.

What I personally find most challenging is defining the right separation of responsibilities among Vite, meta-frameworks, and runtime providers. Ideally, we'd maximize the capabilities of both meta-frameworks and runtime providers while minimizing framework/runtime-specific logic — but we don't yet know what kind of interface could satisfy that. The lack of established conventions also makes things harder. Moreover, I feel it's difficult for me to propose conventions between meta-frameworks and runtime providers, since I don't have a deep enough meta-framework perspective.

In the past, there was a discussion about who should "control" the build (#16358 (reply in thread)). I guess solving Needs 3 and Needs 4 may help this problem.

[sapphi-red]

Regarding Needs 1 / Solution 1:

If there's only one entry point, I think specifying it via config.build.rollupOptions.input works fine. If there are multiple entry points, you'd need routing information like in Needs 3. So in essence, I think Needs 1 is actually subsumed under Needs 3. (Though the RSC bundling issue is a separate concern.)

Note that, as of very recently, TanStack Start and Cloudflare are experimenting with a conventional server-entry export; but it isn’t clear how this would help with a metaframework-agnostic provider plugin. This expects the end user to hook up the entry point, or for this to be done in provider templates, neither of which is (IMO) ideal DX.

If Needs 2 were resolved, we could simply specify server-entry as the default entry point. So, fundamentally, this seems more like one possible solution for Needs 2, rather than a direct solution for Needs 1.

[serhalp]

Yeah. Just to restate this here: if you're writing a single metaframework-agnostic provider build plugin, you can't make the assumption that the app you're building has a single server entry point. It just isn't viable, unless you choose to not support some metaframeworks or not support certain features—but you can't even detect these cases and log an error/warning, for the same reason you can't support it in the first place.

[sapphi-red]

Regarding Solution 2:

I think it would be helpful to have some form of specification (even if loosely defined), but I don't think this is something that the Vite team can or should propose directly. It would be helpful if not only the route but also the middleware is some standardized as that would help migrating the internal middlewares.

[serhalp]

That makes sense, and toward that I proposed to settle on the "Fetchable" interface in the RFC above.

re: internal middleware — Could you tell me more about this? Need 2 was about the built server entry point files that get invoked at production runtime. Aren't Vite internal middlewares a concept that only exists in dev/preview?

[sapphi-red]

Yes, Vite internal middlewares only exists in dev/preview. While these middlewares only run in dev / preview, I think it would make it easier for frameworks / apps to migrate to a runtime agnostic code.

[sapphi-red]

Regarding Solution 3:

I understand the necessity of Needs 3, but I think it's difficult to design an interface that doesn't limit the meta-framework's capabilities. I guess each meta-frameworks would have to know each runtimes capabilities due to the differences, and maybe Vite should focus on how the meta-frameworks and the runtime provider plugins can communicate.

[serhalp]

In our discussions with metaframework maintainers and other providers, we've found good alignment on the scope as defined in the RFC above, namely:

In scope for Vite: Features and functionality involved in the framework fulfilling requests; for example, SSR pages, middleware, RSC, framework-defined API endpoints, Server Functions.
Out of scope for Vite: Everything else; for example, static redirects, static response headers, image optimization, version skew protection, etc. These belong in some combination of framework configuration, provider configuration, and provider plugin/adapter configuration.

and to restate this, our vision is for provider plugins not to have any knowledge of metaframeworks and vice versa.

I think it's very doable to fully solve for request routing within this vision, which is the only thing in scope that isn't solvable at the moment. The "out of scope" features listed above are a whole other beast that I propose we ignore. (Tanner had an idea about this though, but I don't want to muddle this RFC... anyone reading this feel free to ping me on Discord or Bluesky though.)

[sapphi-red]

I'm not against having a way to coordinate the runtime and the meta-frameworks. I just felt it is difficult to come up with a one with a consensus. For example, how would the provider allow metaframeworks to use a new feature that is not possible to describe in the routing metadata? (This is purely a theoretical concern. I don't have a concrete example and I don't have much knowledge on this part.)
But the main point I should have wrote in the initial comment is that, these coordination normally does not directly affect Vite itself and I think it would be better if it can iterate separately from Vite's versions.

[serhalp]

Yes, I think we're saying the same thing here. Additional features that aren't in scope for the framework fulfillment requests will be implemented without (direct) Vite API involvement. In fact we already have some ideas we're noodling on to approach this.

I think request routing is a self-contained problem that we can solve within the Vite layer without expanding further.

[brillout]

Thank you, @serhalp, for sparking this discussion. It's great to see both Netlify and Cloudflare showing interest in this.

The only reason we created Photon was that we didn't see any alternatives, and it hadn't occurred to us to create such an RFC.

Let me suggest actionables, both short- and long-term.

[Short term] Agnostic Netlify/Cloudflare plugins

Goal: Make deploying to Netlify or Cloudflare as simple as adding @netlify/vite-plugin or @cloudflare/vite-plugin to the user's vite.config.js.

// vite.config.js

import cloudflare from '@cloudflare/vite-plugin'

// Works with TanStack, Nitro, Photon, ...
export default {
  plugins: [
    cloudflare()
  ]
}

In other words:

• The user doesn't need to install @photonjs/cloudflare anymore.
• @photonjs/cloudflare is fully deprecated.
• @cloudflare/vite-plugin sets configurations that Photon/Nitro/TanStack understands.

sets configurations that Photon/Nitro/TanStack understands.

This is basically the convention we'd need to agree on.

I briefly spoke with Joël about it (@magne4000, Photon lead), and for @photonjs/cloudflare specifically it's apparently relatively easy. I'll let Joël delve into more details in a separate comment.

@pi0 Is that something Nitro would be interested in as well? WDYT? 👀

From our side, we'd be totally up for starting to work on this, with the goal of fully replacing @photonjs/cloudflare by having users simply add @cloudflare/vite-plugin to their vite.config.js. Ideally, the same happens on the Nitro and TanStack side (CC @tannerlinsley @schiller-manuel), so we naturally end up with a convention.

Same for @netlify/vite-plugin.

One neat thing here is that I don't think we need to involve the Vite team at all. It's just a convention between Netlify/Cloudflare and TanStack/Nitro/Photon (and eventually everyone).

[Short term] Universal middlewares/handlers

Goal: Define request middlewares/handlers that work anywhere.

We started @universal-middleware to address this issue, and ideally, there is a convention we can agree on.

Most notably:

• Dynamic context (e.g. req.user)
• Static context (e.g. the route /product/:id)

We actually already started discussing this (Pooya, Joël, and myself) after meeting at ViteConf. I think the three of us can come up with a good convention.

[Short term] vite-plugin-vercel

Goal: Bring Vercel on board.

Joël is the maintainer of vite-plugin-vercel. We will be reaching out to Vercel to see if they are interested (ideally making it an official Vercel plugin @vercel/vite-plugin).

[Future] Vite Deployment API

Goal: Remove the need for Nitro/Photon as much as possible.

I ain't exactly sure how this would look. It will probably become much clearer after we start working on the short-term actionables above.

Idea: A new Vite CLI command $ vite deploy (together with a new Vite API deploy()).

[Proposal] NPM package naming?

How about we rename the Vite plugins?

- @netlify/vite-plugin
+ @netlify/vite
- @cloudflare/vite-plugin
+ @cloudflare/vite

For me personally, it was a paper cut when I started using it — I kept forgetting whether it's @cloudflare/vite-plugin or @cloudflare/plugin-vite.

It's a low-hanging fruit, IMO.

[magne4000]

I wouldn't consider additional properties as monkey-patching, there are type overrides for this use case.
IMO those types should be defined by a shared library that we would then all use.

[jamesopstad]

I don't think we would want to add additional properties to the Vite config for cross-plugin use cases. Vite already inherits the api key from Rollup for inter-plugin communication, which could possibly be used. The example @magne4000 gave would need to be per-environment though to support future use cases. Generally, I would like to avoid coupling between plugins as much as possible.

[magne4000]

Generally, I would like to avoid coupling between plugins as much as possible

I tend to agree, but that library would exist to enforce the contracts between all actors. From the deployment provider’s point of view, it should just be type definitions.

Vite already inherits the api key from Rollup for inter-plugin communication.

This is a good idea, but as you mentioned, per environment config will be necessary, and api key wouldn't easily allow that

[serhalp]

@jamesopstad I might be missing something — how would a Vite plugin needing to know about another specific Vite plugin allow for decoupling plugins?

🤔 or is the idea not that you'd do .find(plugin => plugin.name = '...') like in those docs but rather that there'd be some identifiable key that all providers look for on api and vice versa for frameworks?

Riffing on these thoughts which appear to be converging with the idea we discussed with @tannerlinsley (cc @eduardoboucas) at ViteConf... something like this?

// @vitejs-community/framework-features

export const VITE_FRAMEWORK_FEATURES_KEY = '__FRAMEWORK_FEATURES__'

export interface FrameworkFeatures {
  responseHeaders?: Record<string, string[]>;
  imageCDN?: {
    enabled: boolean;
    allowedHostPatterns?: string[];
  };
  versionSkewProtection?: {
    enabled: boolean;
    versionIDHeader?: string;
    versionIDCookie?: string;
    versionIDQueryParam?: string;
  };
}

// @tanstack/start-plugin-core

import { VITE_FRAMEWORK_FEATURES_KEY, type FrameworkFeatures } from "@vitejs-community/framework-features"

export default {
  /* ... */
  configResolved(config) {
    this.api[VITE_FRAMEWORK_FEATURES_KEY] = { /* ... */ } satisfies FrameworkFeatures
  }
}

// @netlify/vite-plugin (etc.)

import { VITE_FRAMEWORK_FEATURES_KEY, type FrameworkFeatures } from "@vitejs-community/framework-features"

const getFrameworkFeatures = (plugins: Plugin[]): FrameworkFeatures | null => {
  const frameworkPlugins = plugins.filter(
    plugin => Object.hasOwnProperty(plugin.api, VITE_FRAMEWORK_FEATURES_KEY)
  );
  if (frameworkPlugins.length === 0) return null
  if (frameworkPlugins.length > 1) {
    throw new Error("Found multiple framework plugins, aborting")
  }
  return frameworkPlugins[0].api[VITE_FRAMEWORK_FEATURES_KEY] as FrameworkFeatures
}

// ...

[jamesopstad]

I don't think we would want to add additional properties to the Vite config for cross-plugin use cases. Vite already inherits the api key from Rollup for inter-plugin communication, which could possibly be used. The example @magne4000 gave would need to be per-environment though to support future use cases. Generally, I would like to avoid coupling between plugins as much as possible.

I realise now that this comment wasn't very clear. I meant that I don't think we should add additional properties to the Vite config independently of Vite itself. I absolutely think that additional properties should be added by Vite but they should be part of the official types etc.. Maybe this was too strong though and it would be OK to extend the types to try things out.

@jamesopstad I might be missing something — how would a Vite plugin needing to know about another specific Vite plugin allow for decoupling plugins?

Yeah, the api key does encourage coupling, which might not be a good thing. Your idea of using a shared key to access data on it is interesting though.

[jamesopstad]

Thanks for starting this conversation, @serhalp. We're definitely thinking about this at Cloudflare as well. As the scope of Vite grows, with the Environment API and now Vite+, this seems like the logical next step. Here are some initial thoughts:

Firstly, I think we need to be thinking about this as more directly related to the Environment API. One implication of this is that anything that applies at build time should be reflected as closely as possible in dev. This should apply to any new conventions around specifying server entries, routing manifests etc.. An option here that reflects how we currently implement things in @cloudflare/vite-plugin is that the platform plugin provides the build entries and the dev middleware. It could do so by default, however, using server entries provided by the framework plugin rather than by the user in order to reduce the boilerplate necessary. To me, this makes sense because the platform is a layer above the framework. I feel this relationship should default to zero-config but allow additional customisation by the user as needed.

I also think we could work towards more concretely defining what an environment is and use this as a concept to build upon. Would it be too restrictive for each server environment to have a single server entry? If not, then that seems a good way to establish the contract here. The routing manifest would then be routing requests to environments. It would be a platform concern how these environments then map to deployable units (serverless functions etc.). The server bundles feature in React Router already has a separate environment for each bundle and @vitejs/plugin-rsc uses separate environments for ssr and rsc.

Given the above, we may be able to solve 1 (server entry point location) by having a way to specify the entry for server environments. Perhaps we could even reuse the existing build.ssr option for this as it already accepts a string. The platform plugin could then use this when determining how to populate build.rollupOptions.input and it's own dev middleware. As pointed out elsewhere, 1 could be solved by providing the entry directly in 3 (the routing manifest) but I think it may be cleaner to use the environment name in the manifest and make the entry a separate concern.

Regarding 2 (server entry point signature), we would be in favour of standardising on the fetchable convention with the default export but that's probably not a surprise. Having a standard here would definitely simplify things but I'd be interested to hear any counter arguments to this part of the proposal.

3 (routing metadata) is where most of the complexity lies. Trying to build on top of web standards may help focus things. As I've already mentioned, I think it would be worth exploring the idea of routing to environments and each environment having a single server entry. The key here is to come up with something that doesn't stifle innovation, either on the framework or platform side. Part of me thinks that this could be quite simple and patterns could just use wildcards, similar to Cloudflare's route matching. Input from framework authors is really important here though. As you've highlighted, one advantage of formalising this routing information is that platforms can implement the routing on behalf of users and avoid charging for 404s.

I think that prerendering should also be considered as part of this proposal as it's become a common feature across frameworks. I've also been wondering recently if this should be associated more directly with the environment concept. prerender could be its own environment, for example, so there is a cleaner separation between code that is only used at build time and code that is used for SSR. It's definitely another area where Vite could help to bridge the gap between frameworks and platforms.

There will likely always be some cases where frameworks want to abstract over platform features e.g. image optimisation, caching etc.. Even if some frameworks continue to use adapters then wrapping platform plugins in these adapters would still reduce the maintenance burden when compared to not having platform plugins at all.

Finally, I want to add that Nitro and Photon don't necessarily need to be seen as counter to this proposal. nitro could also be considered a platform plugin, just one that abstracts over multiple platforms. The problems to solve remain the same.

[magne4000]

3 (routing metadata) is where most of the complexity lies. Trying to build on top of web standards may help focus things. As I've already mentioned, I think it would be worth exploring the idea of routing to environments and each environment having a single server entry. The key here is to come up with something that doesn't stifle innovation, either on the framework or platform side. Part of me thinks that this could be quite simple and patterns could just use wildcards, similar to Cloudflare's route matching. Input from framework authors is really important here though. As you've highlighted, one advantage of formalising this routing information is that platforms can implement the routing on behalf of users and avoid charging for 404s.

I’m generally in favor of using URLPattern[] for this and adding support for it in utilities like convert-router. That way, anyone can use whatever format they prefer, as long as it compiles down to URLPattern.
From a framework perspective, we also need to provide tools that let developers attach their entry points to these route patterns. Photon offers a dedicated helper, addPhotonEntry, while Nitro relies on filesystem-based routing and defineHandler. Both approaches have their pros and cons, but we could envision a shared library that exposes the same routing information, which Photon and Nitro could then consume.

Finally, I want to add that Nitro and Photon don't necessarily need to be seen as counter to this proposal. nitro could also be considered a platform plugin, just one that abstracts over multiple platforms. The problems to solve remain the same.

I think we need to see the future of Photon and others as an implementation to this RFC

[serhalp]

I've gone back to the drawing board with all these discussion points and come up with this: #21212. Please share feedback over there! 🙏🏼

[magne4000]

1) Server entry point location

We need a single, predictable place to declare server entries and attach their metadata (routing, runtime, etc.). Centralizing this information makes it easier for frameworks and providers to read and act on it.

Several options have been discussed across this RFC:

• Proposed environment.config.entryPoint
• config.build.rollupOptions.input
• Plugin api key
• Photon currently uses environment.config.photon.entries

Regardless of the final shape, we must be able to attach metadata to each server entry (which environment builds it, which routes point to it, etc.).

As an incremental step, using the Plugin api key provides enough flexibility to iterate before settling on a final design.
@serhalp’s example is a good starting point, and we can define both server entries and routing there:

// @vitejs-community/this-rfc

export const FETCHABLE_SERVER_ENTRIES_KEY = '__FETCHABLE_SERVER_ENTRIES__'

export interface FetchableServerEntry {
  id: string;                // Module ID resolvable by Vite that points to the server entry
  name: string               // Human-readable label for debugging and user-facing messages
  env?: string;              // Examples: 'ssr', 'rsc', 'edge' (details below)
  runtime: 'node' | 'edge';  // Generic hint to help providers choose the build environment
}

// Keying entries helps resolve virtual modules and enables quick cross-references
export interface FetchableServerEntries extends Record<string, FetchableServerEntry> {}

// @tanstack/start-plugin-core

import { FETCHABLE_SERVER_ENTRIES_KEY, type FetchableServerEntry } from "@vitejs-community/this-rfc"

export default {
  /* ... */
  configResolved(config) {
    this.api[FETCHABLE_SERVER_ENTRIES_KEY] = {
      // This entry can be referenced via `virtual:fetchable-server-entry:entryKey`
      entryKey: {
        /* ... */
      },
      /* ... */
    } satisfies FetchableServerEntries
  }
}

@vitejs-community/this-rfc can expose helpers to:

• Collect all entries registered by other plugins
• Enforce typings
• Perform basic sanity checks

How do we choose which env builds which entry?

Each provider should decide which Vite environment builds a given entry, with a sensible fallback to a standard Node runtime. That fallback can be provided by a shared plugin like @vitejs-community/this-rfc.

An entry may explicitly set env to force a specific Vite environment; in that case, the provider must add the entry to rollupOptions.input for that environment.

If env is not set, the provider should infer it from the entry’s metadata. For example, { id: '...', runtime: 'edge' } would be built in the vercel_edge environment.

[magne4000]

3) Routing metadata

• In development, frameworks continue to own their routing as usual.
• During build, providers should be able to read routing metadata and configure their deployment targets accordingly.

Practically, we don’t need to hard‑enforce a "one server entry per environment" rule. If multiple routes end up targeting two different entries within the same environment, @vitejs-community/this-rfc can provide a small utility and companion Vite plugin to merge those entries into a single build target.

Frameworks that declare server entries should declare routing alongside them:

// @vitejs-community/this-rfc

export interface FetchableServerEntry {
  /* ... */
  
  route: URLPattern | URLPattern[]; // Routes that should be handled by this entry
  method: string | string[];        // e.g. 'GET' or ['GET', 'POST']

  // Keep room for experimentation
  // Additional, provider-specific metadata for non-generic or experimental features
  cloudflare?: { /* ... */ };
  vercel?: {
    isr?: number, // Vercel ISR configuration (seconds)
    /* ... */
  };
}

[s1gr1d]

Thoughts around Observability (OpenTelemetry)

Currently, OpenTelemetry relies on import-in-the-middle to apply instrumentation to certain libraries. OTel registers the Customization Hook (import-in-the-middle/hook.mjs) which needs to be preloaded before any application code with node --import.

The exact problem statement is described here: https://github.com/getsentry/esm-observability-guide/tree/main?tab=readme-ov-file#problem-statement

Having to rely on the CLI --import flag for observability with OpenTelemetry is a huge pain in the JavaScript ecosystem. Depending on the deployment platform, it's not always possible to modify the node command. However, some frameworks (like Next.js and SvelteKit) already support an instrumentation file that is either preloaded on the deployment platform or runs before any other application code as it's statically imported while the rest of the application is dynamically import() ed.

I think this proposal for Vite enables an amazing opportunity to solve ecosystem issues around Observability: Instead of each each framework having to implement a wrapped server-entry (like SvelteKit already does), Vite could build and expose the server entry in a way that allows running some code before the application starts. It would depend on the server output, but in general this could look like:

import './instrumentation.mjs';

// dynamically imported, so the instrumentation can be preloaded
import('./server.mjs'); // file which contains code from previous index.mjs server-entry file

Also read the guide for Meta-Frameworks here: https://github.com/getsentry/esm-observability-guide/blob/main/guides/meta-framework-authors.md

[brillout]

@serhalp Maybe creating an RFC repository could be convenient — for a single place for all discussions, organized on a topic-by-topic basis (using GitHub Discussions instead of GitHub Issues).

Name proposal: RFC – Vite Deployment Plugins.

[jamesopstad]

To play devil's advocate a little here, what does this proposal achieve that can't be achieved by a framework wrapping a platform plugin with a platform specific adapter and configuring it that way? I feel that answering this question might help focus things a little. The risk with building this into Vite itself is that it becomes an ever expanding surface area that has to satisfy the requirements of all frameworks and platforms.

[magne4000]

I'll try to answer this:

The main value of this RFC is giving framework authors a way to support many different deployment providers out of the box (plus a simple Node fallback), with minimal code or configuration. At the simplest level, a framework would only need to declare its server entry (point 1). More advanced integrations could expose multiple entries along with routing and other metadata. The big win for framework developers is immediate, universal compatibility with any deployment provider that adopts this RFC.

The risk with building this into Vite itself is that it becomes an ever-expanding surface area that has to satisfy the requirements of all frameworks and platforms.

I completely agree. That’s why I believe the best path forward is to share a dedicated library that enforces conventions, provides typings, and exposes helpful utilities.

[magne4000]

I’d like to expand on my earlier answer.

There are many deployment-provider features we could support, but in my opinion the scope should stay focused on two categories:

• Frameworks with a single catch-all entry point.
  Everything is handled at runtime by the framework, so support is straightforward (e.g., Netlify, Cloudflare, Vercel).

• Frameworks that define multiple routes. For example:

  • Netlify: Use the Framework API to deploy certain routes to the Edge.
  • Cloudflare: If the framework provides a catch-all entry, use it. Otherwise, we can offer a shared utility that merges the multiple entries and applies routing at runtime (similar to Nitro). EDIT 1: We can just force frameworks to provide a catch-all entry. EDIT 2: Actually, a shared utility that merges all entries makes sense because it simplifies how frameworks declare their entries, and it also allows both users and libraries to define their own routes
  • Vercel: Same use case as Netlify for Edge endpoints. Also applies to ISR endpoints.

Advanced features like Netlify’s header-based function matching are outside the initial scope. However, Netlify could easily build on top of this RFC to support them by extending the default behavior:

// @rfc/server-entries

export interface EntryMeta {
  id: string; // Module ID for this entry. Can be a filesystem path or a virtual module.
  method?: HttpMethod | HttpMethod[]; // allowed HTTP methods
  pattern?: URLPatternInput | URLPatternInput[]; // route patterns for this entry
}

// @netlify/server-entries

export interface EntryMeta {
  netlify?: {
    edge?: boolean,
    header?: Record<string, boolean>
  }
}

For framework authors who want to enable this feature, it simply comes down to including netlify alongside the usual metadata:

// pseudo-code — final API still TBD
// somewhere inside the framework’s build/dev pipeline

// Wrap a user-defined entry
addServerEntry({
  id: "awesome-framework/server-entry?userEntry=/home/abc/project/api.ts",
  pattern: "/api/:slug*"
})

// Same idea, but when deployed on Netlify, this entry goes to Edge.
// On other platforms, it’s ignored and handled by the framework at runtime.
addServerEntry({
  id: "awesome-framework/server-entry?userEntry=/home/abc/project/edge.ts",
  netlify: {
    edge: true,
    header: {
      "x-abc": true
    }
  }
})

// Catch-all route
addServerEntry({
  id: "awesome-framework/server-entry",
  pattern: "/:slug*"
})