RFC: Client assets metadata API for SSR #20913

hi-ogawa · 2025-10-09T04:40:16Z

hi-ogawa
Oct 9, 2025
Maintainer

This proposal introduces a new API that enables server code to access client runtime assets metadata required for server-side rendering in a framework agnostic way. This feature is currently prototyped in the package @hiogawa/vite-plugin-fullstack with examples listed below.

Motivation

The new API addresses two critical challenges that every SSR framework must solve:

Asset preloading: Preventing client-side assets waterfalls by knowing which assets to preload
FOUC prevention: Ensuring CSS is loaded with the HTML rendered on the server

Currently, meta-frameworks implement their own solutions for these problems. This proposal aims to provide a unified primitive that frameworks can adopt, reducing complexity and lowering the barrier for new custom frameworks to integrate SSR with Vite.

This proposal also aims to initiate discussion around common SSR asset handling patterns, with the hope of finding more robust and future-proof solutions through community feedback.

Proposed API

`?assets` Query Import

The plugin provides a new query import ?assets to access assets information of the module. There are three variations of the import:

import assets from "./index.js?assets";
import assets from "./index.js?assets=client";
import assets from "./index.js?assets=ssr";

The default export of the ?assets module has the following type:

type Assets = {
  entry?: string;               // Entry script for <script type="module" src=...>
  js: { href: string, ... }[];  // Preload chunks for <link rel="modulepreload" href=... />
  css: { href: string, ... }[]; // CSS files for <link rel="stylesheet" href=... />
}

The goal of this API is to cover the following use cases in SSR applications:

Server entry accessing client entry: Enables the server to inject client-side assets during SSR
- This can also be used for implementing "Island Architecture" - see examples/island

// server.js - Server entry injecting client assets during SSR
import clientAssets from "./client.js?assets=client";

export function renderHtml(content) {
  return `
    <!DOCTYPE html>
    <html>
      <head>
        ${clientAssets.css.map(css => 
          `<link rel="stylesheet" href="${css.href}" />`
        ).join('\n')}
        ${clientAssets.js.map(js => 
          `<link rel="modulepreload" href="${js.href}" />`
        ).join('\n')}
        <script type="module" src="${clientAssets.entry}"></script>
      </head>
      <body>
        ...
  `;
}

Universal routes accessing their assets: Routes shared by CSR and SSR can retrieve their associated assets
- See examples/react-router and examples/vue-router for detailed integrations

// routes.js - Router configuration with assets preloading
export const routes = [
  {
    path: "/",
    route: () => import("./pages/index.js"),
    assets: () => import("./pages/index.js?assets"),
  },
  {
    path: "/about",
    route: () => import("./pages/about.js"),
    assets: () => import("./pages/about.js?assets"),
  },
  {
    path: "/products/:id",
    route: () => import("./pages/product.js"),
    assets: () => import("./pages/product.js?assets"),
  },
];

Server-only pages accessing CSS dependencies: Server-rendered pages can retrieve their CSS assets
- See examples/island

// server.js - Server-side page with CSS dependencies
import "./styles.css"; // This CSS will be included in assets
import "./components/header.css";
import serverAssets from "./server.js?assets=ssr"; // Self-import with query

export function renderHtml() {
  // All imported CSS files are available in serverAssets.css
  const cssLinks = serverAssets.css
    .map(css => `<link rel="stylesheet" href="${css.href}" />`)
    .join('\n');
  // ...
}

Runtime Helpers

The plugin provides a utility function mergeAssets to combine multiple assets objects into a single deduplicated assets object.

import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";

// Example: Merging assets from multiple route components
const route1Assets = await import("./pages/layout.js?assets");
const route2Assets = await import("./pages/home.js?assets");

const mergedAssets = mergeAssets(route1Assets, route2Assets);
// Result: { js: [...], css: [...] } with deduplicated entries

Configuration

The API is enabled by adding the plugin and minimal build configuration:

// vite.config.ts
import { defineConfig } from "vite";
import fullstack from "@hiogawa/vite-plugin-fullstack";

export default defineConfig({
  plugins: [
    fullstack({
      // serverHandler: boolean (default: true)
      // This plugin also provides server middleware using `export default { fetch }`
      // from the `ssr.build.rollupOptions.input` entry.
      // This can be disabled by setting `serverHandler: false`
      // to use alternative server plugins like `@cloudflare/vite-plugin`, `nitro/vite`, etc.
    })
  ],
  environments: {
    client: {
      build: {
        outDir: "./dist/client",
      },
    },
    ssr: {
      build: {
        outDir: "./dist/ssr",
        emitAssets: true,
        rollupOptions: {
          input: {
            index: "./src/entry.server.tsx",
          },
        },
      },
    }
  },
  builder: {
    async buildApp(builder) {
      // Currently, the plugin requires this specific build order
      // to dynamically add client entries
      await builder.build(builder.environments["ssr"]!);
      await builder.build(builder.environments["client"]!);
    }
  }
})

TypeScript Support

TypeScript support for ?assets imports can be enabled by adding the following to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@hiogawa/vite-plugin-fullstack/types"]
  }
}

Examples

Example	Playground
Basic	stackblitz
React Router	stackblitz
Vue Router / SSG	stackblitz
Preact Island	stackblitz
Remix 3	stackblitz
Nitro	stackblitz
Cloudflare	-
Data Fetching	stackblitz

How It Works

For a detailed explanation of the plugin's internal architecture and implementation, see HOW_IT_WORKS.md.

Known limitations

Duplicated CSS build for each environment (e.g. client build and ssr build)
- Currently each CSS import is processed and built for each environment build, which can potentially cause inconsistency due to differing code splits, configuration, etc. This can cause duplicate CSS content loaded on client or break expected style processing.
?assets=client doesn't provide css during dev.
- Due to unbundled dev, the plugin doesn't eagerly traverse the client module graph and ?assets=client provides only the entry field during dev. It's currently assumed that CSS files needed for SSR are the CSS files imported on the server module graph.

Other issues and ideas

See the issue tracker in https://github.com/hi-ogawa/vite-plugins/issues?q=is%3Aissue%20state%3Aopen%20fullstack

Request for Feedback

Feedback is greatly appreciated! I'm particularly interested in hearing from framework authors who have likely implemented their own solutions. Key questions include:

Is the API sufficiently powerful for various use cases?
Are there any implementation considerations or edge cases to be aware of?
How can this API be improved to better serve framework needs?

katywings · 2025-10-21T19:15:05Z

katywings
Oct 21, 2025

We are currently reworking the CSS asset handling in SolidStart and are thinking about implementing a similar import parameter solution for the asset map retrieval. Awesome work on your part with this RFC, the provided examples and the vite-plugin-fullstack project!

Unmounting of stale CSS on clientside nav

One topic that we are still debating is route CSS unmounting on client-side navigation - SolidStart currently does it, making the implementation more complex, but more user friendly. Afaik lots of frameworks don't do it and neither does vite. I wonder what's the general stance of vite core developers on this? Should meta frameworks unmount stale route CSS on clientside nav, or just let it stay and force users to write proper non-global route css?

If the stance is that meta frameworks should do the unmounts, I think that it might be worth it, to discuss implementing a generic unmount handling API next to this RFC (or part of it), or to document best practices in one of the Vite guides.

Assets of lazy loaded components

I am the maintainer of the Solid Lazy Plus library, which provides a lazy wrapper that does server render CSS assets of lazy loaded components (https://codeberg.org/lufrai/solid-lazy-plus). It does this by retrieving the assets from our highly-experimental SolidStart API like so:

import { getManifest } from "solid-start:get-manifest";
// This works in dev & prod
const assets = await manifest.getAssets(id);

In this case, the id is a runtime variable, which makes me wonder if/how this would work with your import parameter based API? Like below?

const assets = await import(`${id}?assets`);

Either way, I think the use case of a dynamic id should definitely be considered in this RFC.

1 reply

hi-ogawa Oct 22, 2025
Maintainer Author

Thanks for the feedback! Both are good points. For the 2nd one, that style of API can be more powerful and it's definitely a consideration. One concern is that how do you allow arbitrary id to be queried? For build, I think that would need entire manifest { [moduleId]: ... } to be emitted for the runtime to use it. The manifest size might not be something we need to worry about on server though.

For the 1st one (unmounting css), there is a feature request of disabling current Vite's automatic css setup behavior and let framework take a full control #19505. If this is the framework's need, Vite can support it as opt-in. But with that, when/how to unmount is completely framework dependent given that framework knows associated assets for routes, so I'm not sure what Vite can provide an API or suggest it specifically.
(My biased take is that I don't worry about unmounting css yet because React's <link precedence /> cannot support it https://react.dev/reference/react-dom/components/link#special-rendering-behavior)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

RFC: Client assets metadata API for SSR #20913

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 1 comment 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

Uh oh!

RFC: Client assets metadata API for SSR #20913

Uh oh!

Uh oh!

hi-ogawa Oct 9, 2025 Maintainer

Motivation

Proposed API

?assets Query Import

Runtime Helpers

Configuration

TypeScript Support

Examples

How It Works

Known limitations

Other issues and ideas

Request for Feedback

Replies: 1 comment · 1 reply

Uh oh!

Uh oh!

katywings Oct 21, 2025

Unmounting of stale CSS on clientside nav

Assets of lazy loaded components

Uh oh!

Uh oh!

hi-ogawa Oct 22, 2025 Maintainer Author

hi-ogawa
Oct 9, 2025
Maintainer

`?assets` Query Import

Replies: 1 comment 1 reply

katywings
Oct 21, 2025

hi-ogawa Oct 22, 2025
Maintainer Author