SB-Template Nuxt

🚀 Production-Ready Nuxt 3 Starter with Superpowers

Stop wasting time on boilerplate. Start building features.

A battle-tested, feature-rich Nuxt 3 template that includes everything you need: modern design system, reusable UI components, i18n support, and CI/CD ready to deploy. Build beautiful, production-ready interfaces in minutes, not weeks.

Quick Start • Features • Components • Deploy

• Core Features
• Ready-to-Use Components
• Quick Start
• Project Structure
• Customization
  • Theme & Styling
  • Internationalization
  • Components
  • Composables
• Deployment
• CI/CD

• Tailwind CSS 4.1.18 - Modern utility-first CSS with custom design tokens
• Custom Theme System - Pre-configured theme with CSS variables for easy customization
• Typography Utilities - 9 ready-to-use text styles (ty-app-hero, ty-app-title, etc.)
• Color Palette - Semantic color system (main, surface, accent, contrast, muted, error)
• Responsive Design - Mobile-first with smooth transitions on all breakpoints
• Dark Mode Ready - Theme structure prepared for dark mode implementation

• @nuxtjs/i18n 10.2.1 - Complete i18n solution
• English & Italian included (easily add more)
• URL Strategy - prefix_except_default (e.g., /page for EN, /it/page for IT)
• Translation Files - JSON-based translations in i18n/locales/

• TheHeader - Responsive navigation with mobile drawer
• TheFooter - Multi-column footer with social links
• TheNotificationBanner - Toast notifications (success, error, warning, info)
• BaseIconMenu - Floating dropdown menu with keyboard navigation
• BaseCloseButton - Accessible close button

Build modern interfaces in minutes. This template includes a complete library of production-ready, accessible, and fully customizable UI components designed to accelerate your development workflow.

Full-featured button component with multiple variants and states.

Variants: primary, secondary, outline Types: button, submit, reset, link States: loading, disabled Features: Icon support, accessible, keyboard navigation

<BaseButton variant="primary" :is-loading="false">
  <Icon name="lucide:send" class="size-5 mr-2" />
  Send Message
</BaseButton>

<BaseButton variant="outline" type="link" to="/about">
  Learn More
</BaseButton>

Text input with label, hints, error states, and prefix icons.

Types: text, email, password, number Features: Validation states, accessible, auto-focus, prefix icons

<BaseInput
  id="email"
  v-model:input="email"
  type="email"
  label="Email Address"
  placeholder="user@example.com"
  prefix-icon="lucide:mail"
  hint="We'll never share your email"
  :error="emailError"
/>

Multi-line text input with character counter.

Features: Character limit, auto-resize, validation states

<BaseTextarea
  id="message"
  v-model:input="message"
  label="Your Message"
  :max-length="500"
  :rows="4"
  placeholder="Type your message..."
/>

Custom checkbox with label slot.

Features: Custom styling, accessible, label slot

<BaseCheckbox id="terms" v-model:input="acceptTerms">
  I agree to the terms and conditions
</BaseCheckbox>

Advanced select component with single/multiple selection.

Types: single, multiple Features: Searchable, keyboard navigation, floating UI, custom icons

<BaseCombobox
  id="country"
  v-model:input="selectedCountries"
  type="multiple"
  :items="countries"
  label="Select Countries"
  prefix-icon="lucide:globe"
  placeholder="Choose countries..."
/>

Compact label component for tags, badges, and status indicators.

Variants: accent, primary, secondary Features: Icon support, rounded design, responsive sizing

<!-- Simple chip -->
<BaseChip text="Featured" variant="accent" />

<!-- Chip with icon -->
<BaseChip
  icon="lucide:star"
  text="Premium"
  variant="accent"
/>

<!-- Use cases -->
<BaseChip icon="lucide:code" text="Vue.js" variant="accent" />
<BaseChip icon="lucide:check-circle" text="Active" variant="accent" />
<BaseChip icon="lucide:folder" text="Design" variant="primary" />

Flexible card container with slots for header, body, and footer.

Variants: dark, light, dark-hover, light-hover Alignment: left, center, right Slots: card-header, card-body, card-footer, default

<BaseCard
  title="Card Title"
  subtitle="Card Subtitle"
  paragraph="Card description text"
  variant="dark-hover"
  align="center"
>
  <template #card-header>
    <Icon name="lucide:star" class="size-6 text-app-accent" />
  </template>

  <template #card-footer>
    <BaseButton variant="primary">Action</BaseButton>
  </template>
</BaseCard>

<!-- Full custom content -->
<BaseCard :full-custom-content="true">
  <div class="custom-layout">
    <!-- Your custom content -->
  </div>
</BaseCard>

Modal dialog with size variants and custom slots.

Sizes: sm, md, lg, full Features: Scroll lock, keyboard (ESC), accessible, click outside to close

<BaseDialog
  :is-open="isDialogOpen"
  size="md"
  title="Dialog Title"
  subtitle="Dialog subtitle"
  @close="isDialogOpen = false"
>
  <template #header>
    <div class="custom-header">
      <!-- Optional custom header content -->
    </div>
  </template>

  <p>Dialog content goes here</p>

  <template #footer>
    <BaseButton variant="outline" @click="isDialogOpen = false">
      Cancel
    </BaseButton>
    <BaseButton variant="primary" @click="handleSave">
      Save
    </BaseButton>
  </template>
</BaseDialog>

Dropdown menu with floating UI and keyboard navigation.

Features: Floating positioning, keyboard support, click outside to close

<BaseIconMenu
  icon="lucide:menu"
  :items="menuItems"
  :selected-item-id="selectedId"
  @select="handleSelect"
/>

<script setup>
const menuItems = [
  { code: 'profile', label: 'Profile', icon: 'lucide:user', iconType: 'nuxt-icon' },
  { code: 'settings', label: 'Settings', icon: 'lucide:settings', iconType: 'nuxt-icon' },
]
</script>

Toast notification system with multiple types.

Types: success, error, warning, info Features: Auto-dismiss, manual close, stacking

<script setup>
const { notify } = useAppNotifications()

notify({
  type: 'success',
  title: 'Success!',
  description: 'Your changes have been saved.',
  duration: 5000,
})
</script>

✅ Accessible - ARIA attributes, keyboard navigation, focus management ✅ Responsive - Mobile-first design with smooth transitions ✅ Customizable - Full theme support with CSS variables ✅ Type-Safe - Complete TypeScript support ✅ Production-Ready - Battle-tested in real projects ✅ i18n Ready - Internationalization support built-in

See all components in action: Run npm run dev and visit the homepage for a complete showcase.

• TypeScript - Full type safety
• ESLint 9.39.1 - Code quality with stylistic rules
• VueUse 14.1.0 - Vue composition utilities
• Floating UI 1.1.9 - Tooltips, popovers, dropdowns
• Auto-imports - Components and composables automatically imported
• Hot Module Replacement - Lightning-fast development

• @nuxt/image 2.0.0 - Automatic image optimization
• Multiple Formats - WebP, AVIF, PNG support
• Responsive Images - Automatic srcset generation
• Cloudinary Ready - Pre-configured provider
• @nuxt/icon 2.1.0 - SVG icon system with Lucide icon collection
• Icon Library - 1000+ Lucide icons ready to use

• GitHub Actions - Pre-configured workflows
• Automated Testing - Lint and build checks on PR
• Release Please - Automated versioning and changelog
• Netlify Preset - Optimized for Netlify deployment (easily switch to Vercel, Cloudflare, etc.)

• Node.js ≥ 24.11.0
• npm / pnpm / yarn

Option 1: Use as GitHub Template (Recommended)

1. Click "Use this template" on GitHub
2. Clone your new repository:

git clone https://github.com/your-username/your-project.git
cd your-project

Option 2: Clone Directly

git clone https://github.com/stefanoBid/sb-nuxt-template.git my-project
cd my-project
rm -rf .git && git init  # Start fresh

# Install dependencies
npm install

# (Optional) Reset version to 0.1.0
echo "# Changelog" > CHANGELOG.md
npm version 0.1.0 --no-git-tag-version

# Start development server
npm run dev

Visit http://localhost:3000 🎉

sb-template-nuxt/
├── app/
│   ├── assets/
│   │   └── css/
│   │       ├── main.css          # Main CSS entry point
│   │       ├── theme.css         # CSS variables & design tokens
│   │       ├── typography.css    # Typography utilities (ty-app-*)
│   │       ├── animations.css    # Animation classes
│   │       └── utilities.css     # Custom utility classes
│   │
│   ├── components/
│   │   ├── base/
│   │   │   ├── button/           # BaseButton.vue - Multi-variant button
│   │   │   ├── card/             # BaseCard.vue - Flexible card container
│   │   │   ├── checkbox/         # BaseCheckbox.vue - Custom checkbox
│   │   │   ├── chip/             # BaseChip.vue - Tag/badge component
│   │   │   ├── close-button/     # BaseCloseButton.vue - Accessible close button
│   │   │   ├── combobox/         # BaseCombobox.vue - Select dropdown
│   │   │   ├── dialog/           # BaseDialog.vue - Modal dialog
│   │   │   ├── icon-menu/        # BaseIconMenu.vue - Dropdown menu
│   │   │   ├── input/            # BaseInput.vue - Text input with validation
│   │   │   └── textarea/         # BaseTextarea.vue - Multi-line input
│   │   ├── the-footer/           # TheFooter.vue
│   │   ├── the-header/           # TheHeader.vue & TheHeaderMenuToggle.vue
│   │   └── the-notification/     # TheNotificationBanner.vue & Box
│   │
│   ├── composables/
│   │   ├── useAppNotifications.ts  # Notification system
│   │   ├── useFloatingUi.ts        # Floating UI helper
│   │   ├── useLockScroll.ts        # Scroll lock utility
│   │   └── useSanitize.ts          # HTML sanitization
│   │
│   ├── layouts/
│   │   └── default.vue             # Default page layout
│   │
│   ├── pages/
│   │   └── index.vue               # Homepage
│   │
│   ├── plugins/
│   │   └── scrollToTop.client.ts   # Auto-scroll on route change
│   │
│   ├── types/
│   │   └── global.d.ts             # Global TypeScript types
│   │
│   ├── utils/
│   │   └── generateUuid.ts         # UUID generator
│   │
│   ├── app.vue                      # Root component
│   └── error.vue                    # Error page
│
├── i18n/
│   └── locales/
│       ├── en.json                  # English translations
│       └── it.json                  # Italian translations
│
├── public/
│   ├── favicon.ico
│   ├── robots.txt
│   └── sitemap.xml                  # SEO sitemap template
│
├── nuxt.config.ts                   # Nuxt configuration
├── tsconfig.json                    # TypeScript configuration
├── eslint.config.mjs                # ESLint configuration
└── package.json

Edit app/assets/css/theme.css to change colors, fonts, and spacing:

@theme {
  /* Fonts */
  --font-app-primary: 'Your Font', system-ui, sans-serif;
  --font-app-secondary: 'Your Mono Font', monospace;

  /* Colors */
  --color-app-main: #f8f9fa;        /* Background */
  --color-app-accent: #2563eb;      /* Primary accent */
  --color-app-contrast: #1a1a1a;    /* Text color */
  --color-app-error: #dc2626;       /* Error state */
  /* ...more colors */
}

💡 Tip: All CSS variables are prefixed with app- to avoid conflicts.

Pre-configured typography classes in app/assets/css/typography.css:

Example:

<template>
  <h1 class="ty-app-hero">Welcome to My App</h1>
  <p class="ty-app-paragraph">This is a paragraph with proper styling.</p>
</template>

Use pre-defined animation classes from app/assets/css/animations.css:

• fade-in / fade-out
• slide-in-up / slide-in-down
• bounce-in

1. Register the locale in nuxt.config.ts:

i18n: {
  locales: [
    { code: 'en', iso: 'en-US', name: 'English', file: 'en.json' },
    { code: 'it', iso: 'it-IT', name: 'Italiano', file: 'it.json' },
    { code: 'fr', iso: 'fr-FR', name: 'Français', file: 'fr.json' }, // ✅ New
  ],
}

2. Create translation file i18n/locales/fr.json:

{
  "welcome": "Bienvenue",
  "nav": {
    "home": "Accueil",
    "about": "À propos"
  }
}

3. Use translations in components:

<template>
  <h1>{{ $t('welcome') }}</h1>
  <NuxtLink :to="localePath('/')">{{ $t('nav.home') }}</NuxtLink>
</template>

<script setup>
const { locale, setLocale } = useI18n()

function changeLanguage(lang: string) {
  setLocale(lang)
}
</script>

<template>
  <button @click="changeLanguage('it')">Italiano</button>
  <button @click="changeLanguage('en')">English</button>
</template>

<script setup>
const { notify } = useAppNotifications()

function showSuccess() {
  notify({
    type: 'success',
    title: 'Success!',
    description: 'Your action was completed.',
    duration: 5000, // Auto-dismiss after 5s
  })
}

function showError() {
  notify({
    type: 'error',
    title: 'Error!',
    description: 'Something went wrong.',
    duration: 0, // Manual dismiss only
  })
}
</script>

<template>
  <button @click="showSuccess">Show Success</button>
  <button @click="showError">Show Error</button>
</template>

Notification Types: success, error, warning, info

<template>
  <BaseIconMenu>
    <template #trigger="{ toggle }">
      <button @click="toggle">
        <Icon name="mdi:menu" />
      </button>
    </template>

    <template #content>
      <div class="p-4 bg-white rounded-lg shadow-lg">
        <a href="/profile">Profile</a>
        <a href="/settings">Settings</a>
        <button @click="logout">Logout</button>
      </div>
    </template>
  </BaseIconMenu>
</template>

Manage toast notifications.

const { notify, removeNotification, notifications } = useAppNotifications()

// Show notification
notify({
  type: 'success',
  title: 'Title',
  description: 'Description',
  duration: 5000, // ms (0 = manual dismiss)
})

// Remove specific notification
removeNotification(id)

Position floating elements (tooltips, dropdowns).

const reference = ref<HTMLElement>()
const floating = ref<HTMLElement>()

const { floatingStyles } = useFloatingUi(reference, floating, {
  placement: 'bottom-start',
  offset: 8,
})

Lock/unlock body scroll (useful for modals).

const { lockScroll, unlockScroll } = useLockScroll()

// Lock scroll when modal opens
onMounted(() => lockScroll())

// Unlock when modal closes
onUnmounted(() => unlockScroll())

Sanitize HTML to prevent XSS attacks.

const { sanitizeHtml } = useSanitize()

const cleanHtml = sanitizeHtml('<script>alert("xss")</script><p>Safe content</p>')
// Result: '<p>Safe content</p>'

<template>
  <!-- Local images (from public/) -->
  <NuxtImg
    src="/images/hero.jpg"
    alt="Hero image"
    width="800"
    height="600"
    format="webp"
    loading="lazy"
  />

  <!-- Cloudinary images -->
  <NuxtImg
    provider="cloudinary"
    src="/sample.jpg"
    alt="Sample"
    width="400"
    height="300"
  />

  <!-- External images (requires domain whitelisting) -->
  <NuxtImg
    src="https://example.com/image.jpg"
    alt="External"
    width="600"
    height="400"
  />
</template>

Configure external domains in nuxt.config.ts:

image: {
  domains: [
    'https://api.example.com',
    'https://cdn.yoursite.com',
  ],
}

<template>
  <!-- MDI icons -->
  <Icon name="mdi:home" size="24" />
  <Icon name="mdi:account-circle" size="32" color="blue" />

  <!-- Flag icons -->
  <Icon name="flagpack:it" size="24" />
  <Icon name="flagpack:us" size="24" />
</template>

Browse available icons:

• MDI Icons
• Flagpack Icons

Create a .env file in the project root:

# API Configuration
NUXT_PUBLIC_API_URL=https://api.yoursite.com

# Cloudinary
NUXT_PUBLIC_CLOUDINARY_BASE=https://res.cloudinary.com/your-cloud-name

# CMS (Strapi, etc.)
NUXT_PUBLIC_STRAPI_URL=https://cms.yoursite.com

# Analytics
NUXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Access in your app:

const config = useRuntimeConfig()
const apiUrl = config.public.apiUrl

⚠️ Important: Only variables prefixed with NUXT_PUBLIC_ are exposed to the client.

This template is pre-configured for Netlify deployment.

1. Build your app:

npm run build

2. Deploy to Netlify:

• Connect your GitHub repository to Netlify
• Build command: npm run build
• Publish directory: .output/public

3. Environment variables: Add your .env variables in Netlify dashboard under Site settings → Environment variables.

1. Change preset in nuxt.config.ts:

nitro: {
  preset: 'vercel',
}

2. Deploy:

npm run build
vercel deploy

1. Change preset:

nitro: {
  preset: 'cloudflare-pages',
}

2. Build and deploy:

npm run build
# Deploy .output/public to Cloudflare Pages

1. Change preset:

nitro: {
  preset: 'node-server',
}

2. Build and run:

npm run build
node .output/server/index.mjs

📚 More deployment options: Nuxt Deployment Docs

This template includes GitHub Actions workflows for automated testing and releasing.

Triggers:

• Push to main, develop, release/** branches
• Pull requests to main

Actions:

1. ✅ Checkout code
2. ✅ Install dependencies (npm ci)
3. ✅ Run linter (npm run lint)
4. ✅ Build app (npm run build)

Smart Skip: The workflow automatically skips heavy steps for Release Please PRs (only marks as passed).

Workflow file: .github/workflows/ci.yml

Trigger: Push to main branch

What it does:

1. Analyzes conventional commits (e.g., feat:, fix:, chore:)
2. Creates/updates a Release PR with:
   • Auto-generated changelog
   • Version bump in package.json
3. When merged, creates a GitHub Release with tags

Commit Message Format:

# Features
git commit -m "feat: add dark mode support"

# Bug fixes
git commit -m "fix: resolve navigation issue on mobile"

# Breaking changes
git commit -m "feat!: redesign authentication system"

# Chores (no release)
git commit -m "chore: update dependencies"

💡 Tip: Use conventional commits to automate versioning!

Workflow file: .github/workflows/release-please.yml

If you want your project to start from version 0.1.0 instead of inheriting the template's version:

# Clear changelog
echo "# Changelog" > CHANGELOG.md

# Reset version
npm version 0.1.0 --no-git-tag-version

# Commit changes
git add .
git commit -m "chore: initialize project from template"

This template is perfect for:

✅ Landing Pages - Fast, SEO-optimized, multi-language ✅ Marketing Sites - With optimized images and analytics ready ✅ Documentation Sites - Custom styling and navigation ✅ SaaS Applications - Notification system and user dashboards ✅ Portfolio Websites - Dynamic routing and image galleries ✅ E-commerce Stores - Product pages with i18n support

• Components: Use PascalCase for component filenames
• Composables: Prefix with use (e.g., useAuth.ts)
• Utils: Pure functions in app/utils/
• Types: Global types in app/types/global.d.ts

• Follow ESLint rules (run npm run lint:fix before committing)
• Use TypeScript for type safety
• Prefer composition API over options API
• Use auto-imports instead of manual imports

• Lazy load components with <ClientOnly> when not needed for SSR
• Use <NuxtImg> instead of <img> for automatic optimization
• Prerender static pages in nuxt.config.ts → routeRules
• Keep bundle size small (check with npm run build -- --analyze)

Issue: Cannot find module 'isomorphic-dompurify' Solution: This is expected during server builds. The module is excluded in nuxt.config.ts → nitro.externals.

Issue: Icons not showing Solution: Make sure icon collections are installed: npm i @iconify-json/mdi @iconify-json/flagpack

Issue: i18n routes not working Solution: Check nuxt.config.ts → i18n.strategy and ensure locale files exist in i18n/locales/

Issue: Images not loading from external domains Solution: Add domain to nuxt.config.ts → image.domains

Contributions are welcome! Here's how you can help:

1. Report bugs - Open an issue with details
2. Suggest features - Share your ideas
3. Submit PRs - Fork, create a branch, and submit a pull request

Development Setup:

git clone https://github.com/stefanoBid/sb-nuxt-template.git
cd sb-nuxt-template
npm install
npm run dev

This project is open source and available under the MIT License.

Feel free to use it for personal or commercial projects.

Stefano Biddau

📧 Email: biddau.stefano99@gmail.com

🐙 GitHub: @stefanoBid

🌐 Website: stefanobiddau.com

Looking for more starter templates? Check out the SB Templates Project collection!

👉 Browse All Templates

Visit the website and navigate to the SB TEMPLATES PROJECT section to discover more production-ready templates for different frameworks and use cases.

If this template helped you build faster, give it a ⭐️ on GitHub!

Your support motivates me to maintain and improve this project.

• Nuxt 3 Documentation
• Vue 3 Documentation
• Tailwind CSS Documentation
• VueUse Documentation
• Nuxt i18n Documentation