@pi0/vite-plugin-fullstack
Advanced tools
> [!NOTE] > This was a draft version of the prospoal, which is now available on [Vite discussion](https://github.com/vitejs/vite/discussions/20913). > Please leave a comment there if you have any feedback.
[!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.
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.
The new API addresses two critical challenges that every SSR framework must solve:
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.
?assets Query ImportThe 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:
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>
...
`;
}
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"),
},
];
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');
// ...
}
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);
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 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"]
}
}
| Example | Playground |
|---|---|
| Basic | stackblitz |
| React Router | stackblitz |
| Vue Router / SSG | stackblitz |
| Preact Island | stackblitz |
| Remix 3 | stackblitz |
| Nitro | stackblitz |
| Cloudflare | - |
| Data Fetching | stackblitz |
For a detailed explanation of the plugin's internal architecture and implementation, see HOW_IT_WORKS.md.
?assets=client doesn't provide css during dev.
?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.Feedback is greatly appreciated! I'm particularly interested in hearing from framework authors who have likely implemented their own solutions. Key questions include:
FAQs
> [!NOTE] > This was a draft version of the prospoal, which is now available on [Vite discussion](https://github.com/vitejs/vite/discussions/20913). > Please leave a comment there if you have any feedback.
We found that @pi0/vite-plugin-fullstack demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.