feat(fullstack): expose Assets.merge method (#1285)

hi-ogawa · web-flow · commit f6b2ece58d1c · 2025-10-16T23:35:04.000+09:00
See updated readme / docs. This reduces the need of accessing `@hiogawa/vite-plugin-fullstack/runtime`. This would help when internalizing entire plugin inside Nitro - nitrojs/nitro#3662
diff --git a/packages/fullstack/README.md b/packages/fullstack/README.md
@@ -53,10 +53,10 @@ export function renderHtml(content) {
     <!DOCTYPE html>
     <html>
       <head>
-        ${clientAssets.css.map(css => 
+        ${clientAssets.css.map(css =>
           `<link rel="stylesheet" href="${css.href}" />`
         ).join('\n')}
-        ${clientAssets.js.map(js => 
+        ${clientAssets.js.map(js =>
           `<link rel="modulepreload" href="${js.href}" />`
         ).join('\n')}
         <script type="module" src="${clientAssets.entry}"></script>
@@ -109,19 +109,24 @@ export function renderHtml() {
 }
 ```
 
-### Runtime Helpers
+### Merging assets
 
-The plugin provides a utility function `mergeAssets` to combine multiple assets objects into a single deduplicated assets object.
+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.
 
 ```js
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
+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
+```
 
-// Example: Merging assets from multiple route components
-const route1Assets = await import("./pages/layout.js?assets");
-const route2Assets = await import("./pages/home.js?assets");
+Alternatively, the package exports `mergeAssets` utility from `@hiogawa/vite-plugin-fullstack/runtime`:
+
+```js
+import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 
 const mergedAssets = mergeAssets(route1Assets, route2Assets);
-// Result: { js: [...], css: [...] } with deduplicated entries
 ```
 
 ### Configuration
diff --git a/packages/fullstack/examples/basic/src/entry.server.tsx b/packages/fullstack/examples/basic/src/entry.server.tsx
@@ -1,7 +1,6 @@
 import { renderToReadableStream } from "react-dom/server.edge";
 import { App } from "./App";
 import "./index.css";
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import clientAssets from "./entry.client.tsx?assets=client";
 import serverAssets from "./entry.server.tsx?assets=ssr";
 
@@ -13,7 +12,7 @@ async function handler(_request: Request): Promise<Response> {
 }
 
 function Root() {
-  const assets = mergeAssets(clientAssets, serverAssets);
+  const assets = clientAssets.merge(serverAssets);
 
   return (
     <html>
diff --git a/packages/fullstack/examples/cloudflare/src/entry.server.tsx b/packages/fullstack/examples/cloudflare/src/entry.server.tsx
@@ -1,7 +1,6 @@
 import { renderToReadableStream } from "react-dom/server.edge";
 import { App } from "./App";
 import "./index.css";
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import clientAssets from "./entry.client.tsx?assets=client";
 import serverAssets from "./entry.server.tsx?assets=ssr";
 
@@ -13,7 +12,7 @@ async function handler(_request: Request): Promise<Response> {
 }
 
 function Root() {
-  const assets = mergeAssets(clientAssets, serverAssets);
+  const assets = clientAssets.merge(serverAssets);
 
   return (
     <html>
@@ -30,7 +29,7 @@ function Root() {
             crossOrigin=""
           />
         ))}
-        <script type="module" src={clientAssets.entry}></script>
+        <script type="module" src={assets.entry}></script>
       </head>
       <body>
         <div id="root">
diff --git a/packages/fullstack/examples/data-fetching/src/framework/entry.server.tsx b/packages/fullstack/examples/data-fetching/src/framework/entry.server.tsx
@@ -1,4 +1,3 @@
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import { RPCHandler } from "@orpc/server/fetch";
 import { renderToReadableStream } from "react-dom/server.edge";
 import { App } from "../app";
@@ -13,7 +12,7 @@ import {
 } from "@tanstack/react-query";
 
 const rpcHandler = new RPCHandler(__rpc_router__);
-const assets = mergeAssets(clientAssets, serverAssets);
+const assets = clientAssets.merge(serverAssets);
 
 async function handler(request: Request): Promise<Response> {
   const rpcResult = await rpcHandler.handle(request, { prefix: "/rpc" });
diff --git a/packages/fullstack/examples/react-router/src/framework/entry.server.tsx b/packages/fullstack/examples/react-router/src/framework/entry.server.tsx
@@ -1,4 +1,3 @@
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import { renderToReadableStream } from "react-dom/server.edge";
 import {
   StaticRouterProvider,
@@ -21,8 +20,7 @@ async function handler(request: Request): Promise<Response> {
   const router = createStaticRouter(dataRoutes, context);
 
   // collect assets from matched routes
-  const assets = mergeAssets(
-    clientEntry,
+  const assets = clientEntry.merge(
     ...(await Promise.all(
       context.matches
         .map(
diff --git a/packages/fullstack/examples/remix/src/framework/entry.server.tsx b/packages/fullstack/examples/remix/src/framework/entry.server.tsx
@@ -1,5 +1,4 @@
 import assert from "node:assert";
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import type { Remix } from "@remix-run/dom";
 import { jsx } from "@remix-run/dom/jsx-runtime";
 import { renderToStream } from "@remix-run/dom/server";
@@ -26,7 +25,7 @@ async function handler(request: Request): Promise<Response> {
   }
 
   // match route and render page
-  const assets = mergeAssets(clientAssets, serverAssets);
+  const assets = clientAssets.merge(serverAssets);
   const match = routes[url.pathname as "/"] ?? routes["*"];
   const content = await (await match()).default();
 
diff --git a/packages/fullstack/examples/vue-router/src/framework/entry.server.ts b/packages/fullstack/examples/vue-router/src/framework/entry.server.ts
@@ -1,4 +1,3 @@
-import { mergeAssets } from "@hiogawa/vite-plugin-fullstack/runtime";
 import { createHead, transformHtmlTemplate } from "unhead/server";
 import { createSSRApp } from "vue";
 import { RouterView, createMemoryHistory, createRouter } from "vue-router";
@@ -24,8 +23,7 @@ async function handler(request: Request): Promise<Response> {
   await router.isReady();
 
   // collect assets from current route
-  const assets = mergeAssets(
-    clientEntry,
+  const assets = clientEntry.merge(
     ...(await Promise.all(
       router.currentRoute.value.matched
         .map((to) => to.meta.assets)
diff --git a/packages/fullstack/src/plugin.ts b/packages/fullstack/src/plugin.ts
@@ -16,7 +16,10 @@ import {
   isRunnableDevEnvironment,
   normalizePath,
 } from "vite";
-import type { ImportAssetsOptions, ImportAssetsResult } from "../types/shared";
+import type {
+  ImportAssetsOptions,
+  ImportAssetsResultRaw,
+} from "../types/shared";
 import {
   parseAssetsVirtual,
   parseIdQuery,
@@ -118,7 +121,7 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
     },
   ) {
     if (ctx.environment.mode === "dev") {
-      const result: ImportAssetsResult = {
+      const result: ImportAssetsResultRaw = {
         entry: undefined, // defined only on client
         js: [], // always empty
         css: [], // defined only on server
@@ -362,7 +365,7 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
                   `[vite-plugin-fullstack] failed to find built chunk for ${meta.id} imported by ${meta.importerEnvironment} environment`,
                 );
               }
-              const result: ImportAssetsResult = {
+              const result: ImportAssetsResultRaw = {
                 js: [],
                 css: [],
               };
@@ -440,6 +443,9 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
               return `\0virtual:fullstack/empty-assets`;
             }
           }
+          if (source === "virtual:fullstack/runtime") {
+            return this.resolve("./runtime.js", import.meta.filename);
+          }
         },
       },
       load: {
@@ -455,12 +461,13 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
             // assets=ssr    => { environment: "ssr",    isEntry: false }
             // assets        => { environment: "client", isEntry: false }, { environment: <this>, isEntry: false }
             const s = new MagicString("");
+            const codes: string[] = [];
             if (value) {
               const code = await processAssetsImport(this, filename, {
                 environment: value,
                 isEntry: value === "client",
               });
-              s.append(`export default ${code};\n`);
+              codes.push(code);
             } else {
               const code1 = await processAssetsImport(this, filename, {
                 environment: "client",
@@ -470,11 +477,12 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
                 environment: this.environment.name,
                 isEntry: false,
               });
-              s.append(
-                `import * as __assets_runtime from "@hiogawa/vite-plugin-fullstack/runtime";\n` +
-                  `export default __assets_runtime.mergeAssets(${code1}, ${code2});\n`,
-              );
+              codes.push(code1, code2);
             }
+            s.append(`
+import * as __assets_runtime from "virtual:fullstack/runtime";\n
+export default __assets_runtime.mergeAssets(${codes.join(", ")});
+`);
             if (this.environment.mode === "build") {
               s.prepend(
                 `import __assets_manifest from "virtual:fullstack/assets-manifest";\n`,
@@ -547,7 +555,7 @@ export function assetsPlugin(pluginOpts?: FullstackPluginOptions): Plugin[] {
   ];
 }
 
-const EMPTY_ASSETS: ImportAssetsResult = {
+const EMPTY_ASSETS: ImportAssetsResultRaw = {
   js: [],
   css: [],
 };
@@ -633,7 +641,7 @@ function hasSpecialCssQuery(id: string): boolean {
 
 type BuildAssetsManifest = {
   [environment: string]: {
-    [import_: string]: ImportAssetsResult;
+    [import_: string]: ImportAssetsResultRaw;
   };
 };
 
diff --git a/packages/fullstack/src/runtime.ts b/packages/fullstack/src/runtime.ts
@@ -1,8 +1,13 @@
-import type { ImportAssetsResult } from "../types/shared";
+import type {
+  ImportAssetsResult,
+  ImportAssetsResultRaw,
+} from "../types/shared";
 
 export type { ImportAssetsResult };
 
-export function mergeAssets(...args: ImportAssetsResult[]): ImportAssetsResult {
+export function mergeAssets(
+  ...args: ImportAssetsResultRaw[]
+): ImportAssetsResult {
   const js = uniqBy(
     args.flatMap((h) => h.js),
     (a) => a.href,
@@ -11,7 +16,9 @@ export function mergeAssets(...args: ImportAssetsResult[]): ImportAssetsResult {
     args.flatMap((h) => h.css),
     (a) => a.href,
   );
-  return { js, css };
+  const entry = args.filter((arg) => arg.entry)?.[0]?.entry;
+  const raw: ImportAssetsResultRaw = { entry, js, css };
+  return { ...raw, merge: (...args) => mergeAssets(raw, ...args) };
 }
 
 // merging is cumbersome because of `data-vite-dev-id` :(
diff --git a/packages/fullstack/types/shared.ts b/packages/fullstack/types/shared.ts
@@ -18,7 +18,11 @@ export type ImportAssetsOptions = {
 };
 
 // TODO: rename to just Assets?
-export type ImportAssetsResult = {
+export type ImportAssetsResult = ImportAssetsResultRaw & {
+  merge(...args: ImportAssetsResultRaw[]): ImportAssetsResult;
+};
+
+export type ImportAssetsResultRaw = {
   entry?: string;
   js: { href: string }[];
   css: CssLinkAttributes[];
