[maartenbreddels]

Solara apps can now serve all their .vue templates and registered components from one bundle that vite builds ahead of time, instead of sending each template's source to the browser to compile there.

Problem

A solara app sends the source of every vue template to the browser, once per kernel, and the browser compiles each one at runtime. For a large app, with a few hundred .vue files, that costs bandwidth and start time, and template errors show up only at runtime. Until now, an app that wanted a build step had to write its own vite entry, name every module and export in Python, and keep the two in sync by hand. Components registered with ipyvue.register_component_from_file could not come from a bundle at all.

Change

An app turns this on with three commands, and its code does not change:

solara vue-bundle src/solara_app.py -o vue/entry.js --vite-config   # the entry, and a starter vite config
vite build -c vue/vite.config.mjs                                   # writes public/vue/app.mjs and app.mjs.json
SOLARA_VUE_BUNDLE=vue/app.mjs solara run src/solara_app.py

• Collecting: solara vue-bundle does not import the app. It bundles every .vue file under the app's folder. It skips node_modules, hidden folders, virtual environments and installed packages, plus anything matched by --exclude. Each export is named <file stem>_<key>, where the key hashes the file's path inside the app and its content, so an edited file gets a new key.

• Building: --vite-config writes a starter config that follows ipyvue's own source-mode rules, so bundle and source behave the same:

  • it rewrites module.exports = to export default, using vite's JS parser;
  • it reads blocks with vue's SFC parser, as ipyvue does;
  • it inserts each template's first <style> under the id ipyvue-<id> the first time the component is created, not when the bundle loads;
  • it ignores scoped unless ipyvue.scoped_css_support is on;
  • it keeps whitespace and asset urls as vue's in-browser compiler does.

  The build also writes app.mjs.json with the exact export list.

• Serving: with SOLARA_VUE_BUNDLE set, the server reads that list at startup and defines the module itself, so app code never names a module. The page gets a modulepreload link with a content-hash url and immutable caching. Solara picks bundle or source per file in two places:

  • its patched get_template, for component_vue and template_file widgets;
  • a patched register_component_from_file, for registered components, also at render time.

  A file whose key is not in the bundle is served from source with one warning, so a stale bundle makes the app slower, never broken. solara vue-bundle --check fails CI on such files.

• Limits: bundle mode works only under solara server, and only for production. Template edits need a restart.

• A fix for every url-backed module: urls under /static/public now get the deployment root path. Master has this bug for every url-backed module.

Registered components need widgetti/ipyvue#119 (register_component_from_esm). Without it, they stay source.

Validation

• The bundle ran on a large production app with a local build of the ipyvue PR above: 201 templates, about 50 components registered at render time, 2.3 MB (about 500 kB gzipped). Five pages matched source mode pixel for pixel. The two remaining differences are a random phone number and an animated dot. A page whose dialog opens on mount keeps its search input focused.
• Opus ran a small app end to end in a browser, with every kind of template, styles, an edited file, and a registration switch. Everything matched source mode, and with the setting off a .vue edit still hot-reloads.
• tests/unit/vue_bundle_test.py (11 tests) and tests/unit/esm_vue_test.py (12 tests) pass locally on ipyvue 1.x.

Gaps

• Nobody tested this with ipyvue 3 / Vue 3, or on Windows. Nobody measured the start-time gain.
• Every .vue file under the app folder runs when the bundle loads. One broken or test-only file blanks every component. CI should smoke-load the bundle (the docs have a snippet), and --exclude can leave files out.
• The widget css trait is ignored for bundled templates.
• Code that imports register_component_from_file before solara patches ipyvue keeps the source path.
• Under flask, urls get no root path, the same as on master.
• Bundled templates insert some styles in a slightly different order than source mode. Nobody saw a visible effect.
• exports.foo = ..., module.exports below the top level, and <script lang="ts"> are not supported. The build fails loudly on the second.

Align results

Caution

/align was not run on this change: Maarten settled the design in chat instead. He chose to re-use this PR, no module names in app code, one bundle per app, a manifest written by the build, readable export names, opt-in per app, solara never running vite, --vite-config behind a flag, and support for registered components.

Crossreview results

The plan had its own crossreview: 3 rounds by astra, opus and sol, before any code. The diff then had two crossreviews, by astra (adversarial), opus (correctness, end to end) and sol (contract). Each ran 3 rounds plus small fixes:

1. On the first version, which collected templates by importing the app.
2. On the redesign that bundles every .vue file and serves registered components, together with the ipyvue PR.

All three approved the final tree, or confirmed the fixes for their own findings.

HIGH findings, all fixed:

• First review:
  • The module.exports rewrite hit comments, block comments, strings and HTML-commented scripts, and left the real assignment, so the whole bundle failed. Fix: vite's JS parser, then vue's SFC parser. Cause: text regexes over JavaScript and SFCs.
• Second review:
  • The collector bundled a venv/ inside the app folder, and one library template that fails at load blanked the app. Fix: skip virtual environments and installed packages.
  • Registered components could not switch between source and bundle, and mounted bundle parents kept old children. Fixed in the ipyvue PR.

MEDIUM findings, all fixed:

• export names read from comments;
• blocks nested inside <template>;
• legacy bare-object scripts;
• an empty script that inserted its style at load;
• CSS containing </script>;
• self-closing blocks;
• local and Docker builds that gave different style ids;
• styles that leaked from unused templates, found on the large app;
• dropped whitespace, which moved badges by 2px;
• mount timing that cost an input its focus.

Small fixes and who confirmed them:

• 39f4fae (the exported value from the parser): astra and sol.
• 709b8e5 (whitespace): measured on a page of the large app.
• b8ffe83 (self-closing blocks in every branch): astra.

Open by choice: the four gaps above (the css trait, early imports, flask root path, style order).

Constitution change that could have prevented these: none.

🤖 Generated with Claude Code

[maartenbreddels]

Parking this PR. We measured the bundle mode thoroughly on a large production app (201 .vue templates, about 70 registered components), in a production-like setup (Caddy in front of 2 uvicorn workers, a 1-core container, HTTP/2 with 40 ms latency, browser CPU at 1x and 4x), and the gain does not justify the risk and the build step.

What the best variant gave against the current release: one minified bundle, preloaded, imported once the websocket connects, and served precompressed by the proxy.

• Home page: 120 to 470 ms faster to the first useful view.
• A page that uses few templates: about 110 ms faster at 1x, but about 130 ms slower at 4x browser CPU. Evaluating the whole bundle costs about as much as compiling those few templates in the browser.
• Websocket traffic: 1.0 to 1.3 MB less per page load.
• Server CPU: only 4 to 9% less. The server's cost is per widget, not per byte: the bundle still creates the same Template and VueComponent widgets, they just carry a url instead of source.

What we learned, in case someone picks this up again:

• Splitting into groups or per-template chunks did not help; one bundle was best.
• Templates must be compiled with the same rules as ipyvue's runtime: first <style> only, ipyvue-<id>, scoped ignored, whitespace preserved. Otherwise pages render differently.
• Registered components must be async, as in source mode, or mount order changes.
• Vue 3 bundles import "vue", so the early import needs another approach there.

The root-path bug in versioned_url() that this work found is fixed separately in #1263.