Troubleshooting Guide
The most common issues when building with vd3, and the one-line fix for each. Most trace back to one of three things: the CSS isn't imported, a composable isn't wired, or DOM is being touched during server rendering.
Symptoms & fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Components look unstyled | The Vanduo CSS isn't loaded. | Add import '@vanduo-oss/vd3/css'; once in your entry file. |
| A widget renders but does nothing | No composable is wired to that subtree. | Call the matching useX(root) composable and bind ref="root" on the section. |
| Build fails: 'window is not defined' | A composable touches the DOM during SSR. | Guard with if (typeof window === 'undefined') return; inside onMounted. |
| Bare import won't resolve in the browser | @vanduo-oss/vd3 ships ESM only and needs a bundler. | Build with Vite/Rollup (or any ESM bundler); there is no IIFE/CDN bundle. |
| Theme doesn't persist on reload | The Vanduo plugin isn't installed, or storage is blocked. | Install VanduoVue via app.use(); useThemePreference() re-hydrates from storage on the client — there is no init() to call. |
| Popup appears in the wrong place | Body-appended overlays position on scroll/resize. | Ensure the page is mounted and the input is visible before opening. |
| Hydration mismatch warning | Server and client rendered different markup. | Keep render output deterministic; defer client-only DOM work to onMounted. |
Still stuck? The vd3 Architecture guide explains the wiring model in depth.