feat(fullstack): prototype import.meta.vite.assets API

[hi-ogawa]

SSR Assets API

This is a proposal to introduce a new API to allow non-client environment to access assets information commonly required for SSR.

Currently, it is prototyped in my package @hiogawa/vite-plugin-fullstack and it provides import.meta.vite.assets function with a following signature:

function assets({ import?: string, environment?: string }): {
  entry?: string;               // script for <script type="module" src=...>
  js: { href: string, ... }[];  // dependency chunks for <link rel="modulepreload" href=... />
  css: { href: string, ... }[]; // dependency css for <link rel="stylesheet" href=... />
};

The goal of this API is to cover following use cases:

• for server entry to access client entry

// [server.js] server entry injecting client entry during SSR
function renderHtml() {
  const assets = import.meta.vite.assets({
    entry: "./client.js",
    environment: "client",
  });
  const head = `
    <script type="module" src=${JSON.stringify(assets.entry)}></script>
    <link type="modulepreload" href=${JSON.stringify(assets.js[0].href)}></script>
    ...
  `;
  ...
}

• for universal route to access assets within its route
  • see examples/react-rotuer and examples/vue-router for concrete examples

// [routes.js] hypothetical router library's routes declaration
export const routes = [
  {
    path: "/about"
    route: () => import("./pages/about.js"),
    routeAssets: mergeAssets(
      import.meta.vite.assets({
        entry: "./pages/about.js",
        environment: "client",
      }),
      import.meta.vite.assets({
        entry: "./pages/about.js",
        environment: "ssr",
      }),
    )
  },
  ...
]

• server only app to access css

// [server.js]
import "./styles.css" // this will be included in `assets.css` below

function renderHtml() {
  const assets = import.meta.vite.assets({
    // both `import` and `environment` is optional and they are default to current module and environment
    // import: "./server.js",
    // environment: "ssr",
  });
  const head = `
    <link type="stylesheet" href=${JSON.stringify(assets.css[0].href)}></script>
    ...
  `;
  ...
}

TODO

MVP

• mvp API design + implementation
  • client entry on server
  • client assets / dependencies on server
  • server css on server
• examples
  • create-vite-extra-like ssr example https://github.com/bluwy/create-vite-extra/
  • @cloudflare/vite-plugin
  • nitro/vite examples https://github.com/nitrojs/vite-examples
  • island
    • client only
    • ssr
    • fresh
  • router library
    • react router
    • vue router
      • scoped css hmr is broken :(
        because of &lang.css vs &lang.css= difference?
        it looks like new css link is returned as text/javascript?
        workarounded by forcing &lang.css via middleware.
• e2e
• docs
• RFC on vite discussion

Future

• API
  • add client entry dynamically
  • transformIndexHtml on server
  • handle server change event (e.g. reload / refetch)
  • deduplicate client and server css on build when css code split differs
    • treat css on server like client reference?
• create custom integration of router libraries
  • react router
  • vue router
• test it on ecosystem framework
  • fresh (server css)

[hi-ogawa]

• feat(fullstack): prototype import.meta.vite.assets API #1168 : 3 dependent PRs (#1170 , #1171 , #1172 ) 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[hi-ogawa]

Merge activity

• Oct 3, 1:18 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• Oct 3, 1:18 AM UTC: @hi-ogawa merged this pull request with Graphite.