Installation & Integration — Guides

Installation & Integration `Guide`

vd3 is a standalone Vue 3 package. Getting a Vanduo-styled app running is three steps: install @vanduo-oss/vd3, import its stylesheet once, and register the VanduoVue plugin. No global runtime, no build-tool plugin, no post-mount initialisation.

Install the package

Add the core package. Reach for @vanduo-oss/vd3-cbun only when you need the canvas components (charts, flowchart, hex-grid, music-player).

# The Vue 3 component library (tokens + CSS + components)
pnpm add @vanduo-oss/vd3

# Optional — the canvas bundle (charts, flowchart, hex-grid, music-player)
pnpm add @vanduo-oss/vd3-cbun

Register the plugin & styles

Import @vanduo-oss/vd3/css once in your entry file so the whole stylesheet is loaded, then install the plugin:

// main.ts — register the plugin and the stylesheet once
import { createApp } from 'vue';
import { VanduoVue } from '@vanduo-oss/vd3';
import '@vanduo-oss/vd3/css';
import App from './App.vue';

createApp(App).use(VanduoVue).mount('#app');

VanduoVue only applies theme defaults — pass themeDefaults to override the generated baseline:

// The plugin takes an optional themeDefaults override, shallow-merged
// over the generated baseline and applied synchronously on install.
app.use(VanduoVue, {
  themeDefaults: { PRIMARY_DARK: 'green' },
});

Option	Type	Description
`themeDefaults`	`Partial<ThemeDefaults>`	Site-specific overrides shallow-merged over the generated theme baseline (e.g. { PRIMARY_DARK: 'green' }). Applied synchronously on install, before the theme model first reads its defaults. Optional.

Use the components

Import Vd* components from @vanduo-oss/vd3 — typed, tree-shakeable, ready to compose:

<!-- App.vue — import typed Vd* components and compose -->
<script setup lang="ts">
import { VdCard, VdButton } from '@vanduo-oss/vd3';
</script>

<template>
  <VdCard>
    <h1 class="vd-h1">Build fast with Vanduo</h1>
    <p class="vd-lead vd-text-muted">First-class Vue 3 components.</p>
    <VdButton variant="primary" size="lg">Get started</VdButton>
  </VdCard>
</template>

Canvas components come from the @vanduo-oss/vd3-cbun subpaths and carry their own CSS:

// Canvas components live under @vanduo-oss/vd3-cbun subpaths,
// each with its own stylesheet.
import { VdChart } from '@vanduo-oss/vd3-cbun/charts';
import '@vanduo-oss/vd3-cbun/charts/css';

vite-ssg & SSR

Every Vd* component is SSR-safe — no window or DOM access at module or setup scope, with browser-only work (observers, listeners) deferred to onMounted. So the components prerender and hydrate cleanly under vite-ssg, Nuxt, or your own SSR. Register the plugin inside the vite-ssg setup callback:

// main.ts — SSR / SSG entry with vite-ssg
import { ViteSSG } from 'vite-ssg';
import { VanduoVue } from '@vanduo-oss/vd3';
import '@vanduo-oss/vd3/css';
import App from './App.vue';
import { routes } from './routes';

export const createApp = ViteSSG(App, { routes }, ({ app }) => {
  // Set your theme default here so the first prerendered paint matches.
  app.use(VanduoVue, { themeDefaults: { PRIMARY_DARK: 'green' } });
});

Import @vanduo-oss/vd3/css in the entry so the stylesheet is baked into the prerendered HTML (no flash of unstyled content).
Set your theme default via themeDefaults in the setup callback so the first server-rendered paint matches the client.
This very site is built with vite-ssg and prerenders every route against these components.

Next steps

vd3 Architecture GuideTokens to CSS to components — how the package is built.Migrating from vanduo v2 to vd3 GuidePackage map, import changes, and API diffs.Browse components ComponentStart with Button and explore the reference.

Installation & Integration Guide