@bitboss-dev/bitboss-ui-nuxt

🎨 Bitboss UI Nuxt

Bitboss UI Nuxt is a powerful Nuxt 3 module that seamlessly integrates Bitboss UI components with enhanced features like form validation, auto-generated icon types, and flexible configuration options.

✨ Features

• 🚀 Zero-config setup - Works out of the box with sensible defaults
• 🎯 TypeScript support - Full type safety for components and icons
• ✅ Form validation - Integrated with vee-validate for robust form handling
• 🎨 Auto-generated icon types - Type-safe icon usage from your SVG assets
• 🎭 Flexible styling - Configurable stylesheet injection
• 🔗 Enhanced links - Customizable link component integration
• 📦 Tree-shakable - Only bundle what you use

📦 Installation

Install the module and its peer dependencies:

npm install bitboss-ui
npx nuxi module add @bitboss-dev/bitboss-ui-nuxt

Validation is disabled by default but if you want to include validated components you need to install peerDependencies as well.

npm install @vee-validate/rules vee-validate fast-equals

Add it to your nuxt.config.ts if not already added by nuxi:

export default defineNuxtConfig({
	modules: ['@bitboss-dev/bitboss-ui-nuxt'],
});

⚙️ Configuration

Bitboss UI Nuxt by default enables everything apart from validated components as it aims to facilitate integration of bitboss-ui without being a hurdle to config in itself.

export default defineNuxtConfig({
	modules: ['bitboss-nuxt'],
	bitboss: {
		// Log level for debugging (default: 'INFO')
		logLevel: 'INFO', // 'ERROR' | 'WARN' | 'INFO'

		// Icon configuration
		icons: {
			enabled: true, // Enable/disable icon plugin (default: true)
			path: 'assets/icons', // Path to your SVG icons (default: 'assets/icons') relative to the source folder
		},

		// Styles configuration
		styles: {
			enabled: true, // Enable/disable stylesheet injection (default: true)
			index: 0, // CSS injection order (default: 0) useful to work around reset sheets
		},

		// Link component configuration
		link: {
			enabled: true, // Enable/disable enhanced link component (default: true)
			name: 'NuxtLink', // Component name for the link (default: 'NuxtLink')
		},

		// Component configuration
		components: {
			enabled: true, // Enable/disable component auto-import (default: true)
			validation: false, // Enable validation features (default: false)
		},

		// Composables configuration
		composables: {
			enabled: true, // Enable/disable composable auto-import (default: true)
		},
	},
});

🎨 Disable Features

You can disable any feature by setting it to false:

bitboss: {
  icons: false,        // Disable icons completely
  styles: false,       // Disable styles
  components: false,   // Disable components
  composables: false   // Disable composables
}

🎯 Usage

Icons

Bitboss UI Nuxt automatically scans your icon folder and generates TypeScript types for type-safe icon usage:

<template>
	<!-- Type-safe icon usage -->
	<BbButton icon="heart"> Like this </BbButton>

	<!-- Icon in input -->
	<BbTextInput v-model="search" prepend:icon="search" placeholder="Search..." />
</template>

Setup your icons:

1. Place your SVG files in assets/icons/ (or configure a different path)
2. The module will automatically generate types for all .svg files
3. Use icon names without the .svg extension

Form Validation

When validation: true is enabled, all form components automatically integrate with vee-validate. vee-validate is a peerDependency so you need to configure and enable in you project.

// validation/index.ts
import { defineRule } from 'vee-validate';
import { required } from '@vee-validate/rules';

defineRule('required', required);

<!-- app.vue -->
<script setup lang="ts">
import "./validation/index";
</script>

<template>
  <NuxtPage />
</template>

<template>
	<BbForm @submit="onSubmit">
		<BbTextInput
			v-model="email"
			label="Email"
			rules="required|email"
			placeholder="Enter your email"
		/>

		<BbTextInput
			v-model="password"
			label="Password"
			type="password"
			rules="required|min:8"
			placeholder="Enter your password"
		/>

		<BbButton type="submit" :loading="isSubmitting"> Sign In </BbButton>
	</BbForm>
</template>

<script setup lang="ts">
const email = ref('');
const password = ref('');

const onSubmit = (values) => {
	console.log('Form submitted with:', values);
};
</script>

Enhanced Link Component

The module provides a plugin that enables BaseButton and BbButton to also work like RouterLInk:

<template>
	<BaseButton to="/about">About</BaseButton>
	<BbButton to="/contact" class="btn">Contact</BbButton>
</template>

🛠️ API Reference

Configuration Options

logLevel

Controls the verbosity of logging output.

• Type: 'ERROR' | 'WARN' | 'INFO'
• Default: 'INFO'
• Description: Set the minimum log level to display

icons

Configuration for the icon system.

• Type: false | { enabled?: boolean; path?: string }
• Default: { enabled: true, path: 'assets/icons' }
• Description: Configure icon auto-import and type generation

styles

Configuration for stylesheet injection.

• Type: false | { enabled?: boolean; index?: number }
• Default: { enabled: true, index: 0 }
• Description: Control how and when Bitboss UI styles are injected

link

Configuration for the enhanced link component.

• Type: false | { enabled?: boolean; name?: string }
• Default: { enabled: true, name: 'NuxtLink' }
• Description: Configure the link component behavior

components

Configuration for component auto-import.

• Type: false | { enabled?: boolean; validation?: boolean }
• Default: { enabled: true, validation: false }
• Description: Control component availability and validation features

composables

Configuration for composable auto-import.

• Type: false | { enabled?: boolean }
• Default: { enabled: true }
• Description: Enable/disable composable functions

Made with ❤️ by the Bitboss team