{"id":12016,"library":"shadcn-nuxt","title":"Shadcn Nuxt Module","description":"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.","status":"active","version":"2.6.2","language":"javascript","source_language":"en","source_url":"https://github.com/unovue/shadcn-vue","tags":["javascript"],"install":[{"cmd":"npm install shadcn-nuxt","lang":"bash","label":"npm"},{"cmd":"yarn add shadcn-nuxt","lang":"bash","label":"yarn"},{"cmd":"pnpm add shadcn-nuxt","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the module to integrate with the Nuxt.js framework.","package":"nuxt","optional":false}],"imports":[{"note":"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.","wrong":"import shadcnNuxt from 'shadcn-nuxt'","symbol":"\"shadcn-nuxt\"","correct":"export default defineNuxtConfig({\n  modules: [\n    'shadcn-nuxt'\n  ]\n})"},{"note":"Module-specific options are passed via the `shadcn` property within the `defineNuxtConfig` object, adhering to Nuxt's module configuration patterns.","wrong":"import { shadcn } from 'shadcn-nuxt'","symbol":"shadcn (config property)","correct":"export default defineNuxtConfig({\n  shadcn: {\n    prefix: '',\n    componentDir: './components/ui'\n  }\n})"},{"note":"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`.","wrong":"import { Button } from '@/components/ui/Button.vue'","symbol":"Components (e.g., Button)","correct":"<template>\n  <Button>Click me</Button>\n</template>"}],"quickstart":{"code":"import { defineNuxtConfig } from 'nuxt'\n\nexport default defineNuxtConfig({\n  modules: [\n    'shadcn-nuxt'\n  ],\n  shadcn: {\n    /**\n     * Prefix for all the imported component\n     */\n    prefix: '',\n    /**\n     * Directory that the component lives in.\n     * @default \"./components/ui\"\n     */\n    componentDir: './components/ui'\n  }\n})\n\n// In a Vue component (e.g., app.vue or any page/component file)\n<script setup lang=\"ts\">\n// Button component is auto-imported by shadcn-nuxt\n</script>\n\n<template>\n  <div>\n    <h1>Welcome to Nuxt with Shadcn Vue!</h1>\n    <Button>Click me</Button>\n  </div>\n</template>","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.5.2"},{"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`).","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<2.6.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The package was not installed or installed incorrectly, or `nuxt.config.ts` is not correctly configured for TypeScript.","error":"Cannot find module 'shadcn-nuxt' or its corresponding type declarations."},{"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`).","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.","error":"Component is not defined"},{"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`).","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.","error":"Failed to resolve component: <ComponentName>"},{"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.","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.","error":"Tailwind CSS compilation error: 'Your custom CSS contains `tailwind` directives that cannot be used with your current `plugins` configuration.'"}],"ecosystem":"npm"}