> [!NOTE] > This was a draft version of the prospoal, which is now available on Vite discussion. > Please leave a comment there if you have any feedback.

Proposal: Client assets metadata API for SSR

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.

Motivation

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

1. Asset preloading: Preventing client-side assets waterfalls by knowing which assets to preload
2. 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 
      
      
        ...
  `;
}

• 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 => ``)
    .join('\n');
  // ...
}

Merging assets

Each ?assets import provides a merge method to combine multiple assets objects into a single deduplicated assets object. This is useful for aggregating assets from multiple route components or modules.

import route1Assets from "./pages/layout.js?assets";
import route2Assets from "./pages/home.js?assets";

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

Alternatively, the package exports mergeAssets utility from @hiogawa/vite-plugin-fullstack/runtime:

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

const mergedAssets = mergeAssets(route1Assets, route2Assets);

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) {
      // The plugin requires "ssr -> client" build order to support dynamically adding client entries
      await builder.build(builder.environments["ssr"]!);
      await builder.build(builder.environments["client"]!);
      // `writeAssetsManifest` is exposed under `builder` to allow flexible build pipeline
      await builder.writeAssetsManifest()
    }
  }
})

TypeScript Support

TypeScript support for ?assets imports is automatically enabled if @hiogawa/vite-plugin-fullstack is imported in the project. Additionally, the package provides @hiogawa/vite-plugin-fullstack/types to only enable ambient types, which can be referenced through tsconfig.json, for example:

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

Examples

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.

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?