Shadcn Nuxt Module

2.6.2 · active · verified Sun Apr 19

shadcn-nuxt is a Nuxt.js module designed to seamlessly integrate shadcn/ui components (specifically the Vue implementation, shadcn-vue) into Nuxt 3 applications. It automates the setup and configuration process, offering features like automatic import of components into your Nuxt project, abstracting away manual configuration of Tailwind CSS and component paths. The current stable version is 2.6.2, with frequent bug fixes and feature enhancements, indicating an active development cycle. Key differentiators include its robust auto-import mechanism, support for multiple component directories with custom prefixes, and alignment with the upstream shadcn-ui API for consistency. It aims to simplify the developer experience by providing a pre-configured solution for using shadcn-vue's UI library within the Nuxt ecosystem.

Common errors

```
Cannot find module 'shadcn-nuxt' or its corresponding type declarations.
```
cause The package was not installed or installed incorrectly, or `nuxt.config.ts` is not correctly configured for TypeScript.

fix Ensure `shadcn-nuxt` is installed as a dev dependency (`pnpm add -D shadcn-nuxt` or `npm install --save-dev shadcn-nuxt`) and that `nuxt.config.ts` is a TypeScript file.
```
Component is not defined
```
cause The component has not been added to the project via `shadcn-vue add`, or the `componentDir` in `nuxt.config.ts` is incorrect, preventing auto-import.

fix Run `npx shadcn-vue add <ComponentName>` to scaffold the component into your project. Verify that `shadcn.componentDir` in `nuxt.config.ts` correctly points to the directory where your shadcn-vue components reside (e.g., `./components/ui`).
```
Failed to resolve component: <ComponentName>
```
cause The component has not been added to the project via `shadcn-vue add`, or the `componentDir` in `nuxt.config.ts` is incorrect, preventing auto-import.

fix Run `npx shadcn-vue add <ComponentName>` to scaffold the component into your project. Verify that `shadcn.componentDir` in `nuxt.config.ts` correctly points to the directory where your shadcn-vue components reside (e.g., `./components/ui`).
```
Tailwind CSS compilation error: 'Your custom CSS contains `tailwind` directives that cannot be used with your current `plugins` configuration.'
```
cause Tailwind CSS is not correctly configured in your Nuxt project, or the `shadcn-nuxt` module's Tailwind integration is conflicting with an existing setup.

fix Ensure Tailwind CSS is correctly installed and configured in your Nuxt project, including `postcss.config.js`. Verify that `shadcn-nuxt` is listed in your `modules` array. If you have a custom Tailwind configuration, check for conflicts with how `shadcn-nuxt` expects it to be set up. Consult the `shadcn-nuxt` documentation for specific Tailwind integration steps.

Warnings

breaking The `shadcn-nuxt` module updated its internal API to align with `shadcn-ui` in v2.6.0. While specific breaking changes are not explicitly listed, this often implies changes in configuration options or component usage patterns for closer parity with the upstream `shadcn-ui` philosophy.
Fix: Consult the official `shadcn-vue` documentation and `shadcn-nuxt` changelog for specific migration steps. Re-evaluate your `nuxt.config.ts` `shadcn` configuration and component usage.
gotcha Configuring multiple component directories with `componentDir` as an array (e.g., `['@/components/ui', { path: '@/components/ai', prefix: 'Ai' }]`) is supported to prevent Nuxt's default auto-import scanning from causing console warnings. Failing to configure these paths correctly within the `shadcn` module options can lead to unexpected import behavior or warnings.
Fix: Ensure all custom component directories intended for Shadcn Vue components are explicitly listed within the `shadcn.componentDir` array in `nuxt.config.ts`. Utilize prefixes for clarity and to prevent naming conflicts.
gotcha While `shadcn-nuxt` sets up the module integration, it does not automatically install or scaffold individual Shadcn Vue components. Developers still need to run `npx shadcn-vue add <component-name>` (or the equivalent `npx nuxt shadcn-vue add <component-name>` if `shadcn-nuxt` provides a CLI wrapper) to fetch the component code into their project's `componentDir`.
Fix: After installing `shadcn-nuxt` and configuring it, use the `shadcn-vue` CLI (or the integrated Nuxt CLI command if available) to add desired components to your project's configured `componentDir` (e.g., `npx shadcn-vue add button`).
gotcha Older versions of `shadcn-nuxt` or `shadcn-vue` CLI might have had issues resolving `tsconfig.json` path aliases correctly, particularly for nested paths or when multiple alias prefixes were used. This could lead to component not found errors or incorrect scaffolding.
Fix: Ensure you are on `shadcn-nuxt` version `2.6.2` or higher to benefit from improved alias resolution. Double-check your `tsconfig.json` paths and `shadcn.componentDir` configuration for consistency. Manually verify the generated component paths after running `npx shadcn-vue add`.

Install

npm install shadcn-nuxt npm
yarn add shadcn-nuxt yarn
pnpm add shadcn-nuxt pnpm

Imports

"shadcn-nuxt"
wrong:
```
import shadcnNuxt from 'shadcn-nuxt'
```
correct:
```
export default defineNuxtConfig({
  modules: [
    'shadcn-nuxt'
  ]
})
```
This package is a Nuxt module and is configured in `nuxt.config.ts` by adding its name string to the `modules` array. It does not export JavaScript symbols for direct import in client-side or server-side application logic.
shadcn (config property)
wrong:
```
import { shadcn } from 'shadcn-nuxt'
```
correct:
```
export default defineNuxtConfig({
  shadcn: {
    prefix: '',
    componentDir: './components/ui'
  }
})
```
Module-specific options are passed via the `shadcn` property within the `defineNuxtConfig` object, adhering to Nuxt's module configuration patterns.
Components (e.g., Button)
wrong:
```
import { Button } from '@/components/ui/Button.vue'
```
correct:
```
<template>
  <Button>Click me</Button>
</template>
```
Components are automatically registered and imported by Nuxt through this module, eliminating the need for explicit `import` statements in `.vue` files, provided they are correctly added via `shadcn-vue add` and reside in the configured `componentDir`.

Quickstart

Demonstrates how to install `shadcn-nuxt` as a Nuxt module and configure it in `nuxt.config.ts`, followed by a basic example of using an auto-imported Shadcn Vue component in an application.

import { defineNuxtConfig } from 'nuxt'

export default defineNuxtConfig({
  modules: [
    'shadcn-nuxt'
  ],
  shadcn: {
    /**
     * Prefix for all the imported component
     */
    prefix: '',
    /**
     * Directory that the component lives in.
     * @default "./components/ui"
     */
    componentDir: './components/ui'
  }
})

// In a Vue component (e.g., app.vue or any page/component file)
<script setup lang="ts">
// Button component is auto-imported by shadcn-nuxt
</script>

<template>
  <div>
    <h1>Welcome to Nuxt with Shadcn Vue!</h1>
    <Button>Click me</Button>
  </div>
</template>

view raw JSON →