Nuxt

There is no separate package to install for Nuxt. The module is an export of the library itself, and this documentation site runs on it.

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['bitboss-ui/nuxt'],
    css: ['bitboss-ui/styles.css'],
    bitboss: {
        iconDir: './assets/icons',
    },
});

The module ships with the library

bitboss-ui/nuxt does two things and nothing else: it pushes the library's Vite plugin into the Nuxt build, and it adds the runtime plugin. Its config key is bitboss, and the options it takes are the Vite plugin's options — the same object either way, so a project moving between Vite and Nuxt moves its config across unchanged.

That is why Installation documents one set of options for both. Everything configurable lives at build time; only locale stays editable at runtime, through useBbConfig().

Every option

Option	Default	What it does
`iconDir`	`'./assets/icons'`	Folder of SVG files, scanned recursively, relative to the source directory
`locale`	—	The active locale. The one option still editable at runtime
`enabledLocales`	your `locale` plus `'en'`	Which built-in dictionaries enter the bundle
`injectStyles`	`true`	Injects the stylesheet at runtime, before non-library styles
`resetCss`	`false`	Injects the library reset stylesheet
`injectDirectives`	`true`	Registers `v-bb-tooltip`, `v-bb-dropdown`, `v-bb-color`, `v-bb-date`, `v-bb-time`
`requiredAsterisk`	`false`	A red `*` beside the label of `required` fields
`iconDefaultSizes`	`xs` 12 … `2xl` 40	The size scale `BbIcon` and avatars read
`mcp`	`false`	Registers the MCP server in project agent configs on dev boot
`vscodeSettings`	`true`	Registers the local-icons collection so Iconify IntelliSense previews them

enabledLocales is worth a second look. The library ships more than twenty dictionaries but only the enabled ones — plus their dayjs calendar packs — enter the build. The list auto-completes with your locale and 'en', the per-key fallback anchor, so it never needs to repeat them. There is deliberately no 'all': enabling a locale is an explicit, visible bundle cost, and selecting one you did not enable is a compile error, not a runtime fallback.

Two options write files on your machine during dev, and both say so when they do. vscodeSettings edits .vscode/settings.json — idempotently, preserving comments, formatting and key order — and can be turned off. mcp writes into .mcp.json, .cursor/mcp.json and .vscode/mcp.json, merge-safely, leaving any other servers alone. That is the same registration npx bitboss-ui ai-init does. Unlike that command it never installs anything, so run ai-init once for the server's peers. See AI agents.

Registering variants

The variant registries are plugin options too, so in Nuxt they live in the same bitboss block:

bitboss: {
    buttonVariants: ['primary', 'outline', 'secondary', 'ghost', 'destructive', 'link', 'success'],
}

Registering the name makes it type-check. You still own its CSS — see Design language, which covers both halves and what happens if you do only one.

The registries are buttonVariants, alertVariants, badgeVariants, confirmVariants, dropdownItemVariants, tooltipVariants, toastVariants and indicatorVariants. Passing a list replaces the defaults, so include the built-in names you still use.

Icons in Nuxt

Everything else about naming, the build-time literal scan, and where components already accept an icon is in Icons.

Prerendering and SSR

The components server-render. This site runs nuxt generate with failOnError enabled and does not wrap library components in ClientOnly. The route count changes with the documentation corpus, so the build result is the source of truth.

Two things to know when a page fetches its own options:

prefill: true on BbSelect runs in onServerPrefetch, so it is the SSR-friendly setting when the selection has to be in the server-rendered HTML.
The default 'interaction' defers the load to the client, which is usually what you want and is why it is the default.

Fetching data has the full matrix.

If a theme has to survive the first paint on a static site, remember that the reader's theme is not knowable at build time. Apply the class from an inline script in head before hydration, or the page flashes the wrong theme — Design tokens explains why color-scheme follows the class rather than the OS preference.

If you have bitboss-nuxt installed

@bitboss-dev/bitboss-ui-nuxt is a separate, v2-era package. It predates this module, and its API shows it: unprefixed icon names, a components.validation switch, and BaseButton rather than BbBaseButton.

Migrating off it is mostly deletion:

Remove @bitboss-dev/bitboss-ui-nuxt from modules and from package.json, and add 'bitboss-ui/nuxt'.
Move icons.path to iconDir, and drop icons.enabled, styles, link, components and composables — the equivalents are either the defaults or the options in the table above.
Prefix your own icon names with local:, which v3 requires. See Icons.
Import validated controls from bitboss-ui/validated instead of flipping components.validation — see Validated forms.

Then work through Migrating from v2, because a project on that module is on v2 of the library as well.