Struggling with Nuxt UI v2 → v3 migration + Tailwind issues
I'm having quite a few difficulties migrating from Nuxt UI v2 to v3 and would love to hear about your experiences.
Current setup:
Nuxt 3.x
Nuxt UI v3
Tailwind CSS v4.1.11
Issues encountered:
🔴 Tailwind classes being ignored: Some classes like font-bold, font-semibold don't apply at all (not showing up in DevTools inspector)
🔴 CSS configuration: I have @import "tailwindcss" and @import "@nuxt/ui" in my main.css with a @theme directive, but behavior is inconsistent
🔴 Documentation gaps: Migration docs mention Tailwind Variants changes but not issues with basic classes that stop working
Questions:
Have you experienced similar issues with font-weight classes in v3?
Are there specific configs needed to make Tailwind v4 work properly with Nuxt UI v3?
Any migration experience/tips you can share?
Happy to share my config if it helps! Thanks in advance 🙏
8 Replies
Hi @QuRo. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
----------------------
Migrating from Nuxt UI v2 to v3 with Tailwind CSS v4 can indeed introduce some challenges, especially around theming and class application. Here’s what the knowledge sources say about your issues:
1. Tailwind classes like
font-bold/font-semibold not applying
This is a known change with Nuxt UI v3 and Tailwind CSS v4. Nuxt UI v3 adopts a CSS-first configuration using the @theme directive in your CSS, rather than the old tailwind.config.js approach. If you want to customize things like font weights globally, you should do so via the @theme directive in your main.css:
If you want to override component styles (e.g., make all buttons font-bold), you should use the new app.config.ts structure:
This will override the default font weight for all buttons globally. For per-instance overrides, use the class or ui prop on the component itself. The new system uses Tailwind Variants, so overrides must target the correct slot (e.g., base for most root elements) Customize theme.
2. CSS configuration and @theme directive
Your setup with @import "tailwindcss" and @import "@nuxt/ui" in main.css is correct. The @theme directive is now the main way to define design tokens (fonts, colors, breakpoints, etc.) for Tailwind v4 and Nuxt UI v3. Make sure you do not use a tailwind.config.js file anymore, as it is obsolete in this setup Theme.
3. Migration and documentation gaps
- The migration guide emphasizes that all theming and overrides should now be done via CSS variables in @theme and via the new app.config.ts structure. Old overrides (e.g., font: 'font-bold') are obsolete and must be replaced with the new slot-based approach Updated theming system.
- If you’re seeing classes not being applied, double-check that you’re using the correct slot names and that your CSS is being loaded (check the order in nuxt.config.ts).
4. Tips and troubleshooting
- Delete your old tailwind.config.js and rely on the @theme directive in your CSS.
- Use the correct slot names when overriding component styles in app.config.ts or via the ui prop.
- Wrap your app with <UApp> in app.vue for global configuration to work.
- If you need Tailwind to pick up classes in markdown or other sources, use the @source directive in your CSS Theme.
Example: Overriding button font globally
Example: Overriding font in CSS
---
If you’re still having issues, sharing your main.css, app.config.ts, and nuxt.config.ts would help pinpoint the problem. But the above steps should resolve most font-weight and theming issues in Nuxt UI v3 with Tailwind v4 Migration Theme Customize theme.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@398518214532923400> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai I don't want to overide ui component. I have this kind of issue in a simple <span> tag like <span class="font-bold">test</span>
Let me check the knowledge base for you again. One moment! :books:
----------------------
If the Tailwind class like
Your
You do not need to override anything in
- Make sure you have removed any old
If you still don’t see
You should be able to use
font-bold is not applying to a simple element such as <span class="font-bold">test</span>, even outside of Nuxt UI components, this usually points to a Tailwind CSS configuration or build issue.
With Nuxt UI v3 and Tailwind CSS v4, you should define your theme and design tokens using the @theme directive in your CSS, and not rely on tailwind.config.js for extending classes like before. Here’s what you should check:
1. Ensure your CSS is loaded correctlyYour
main.css should look like this:
And in your nuxt.config.ts:
This ensures Tailwind utilities like font-bold are available globally Theme.
2. No need to override for basic classesYou do not need to override anything in
app.config.ts for standard Tailwind classes like font-bold to work on regular HTML elements.
3. If classes are still missing:- Make sure you have removed any old
tailwind.config.js files, as Tailwind v4 with Nuxt UI v3 uses the CSS-first approach.
- If you are using Nuxt Layers or have a monorepo, ensure that your @source directives in your CSS point to all directories containing files with Tailwind classes, so Tailwind can scan them properly Theme - @source.
4. Check for build issuesIf you still don’t see
font-bold in the DevTools, try restarting your dev server and clearing .nuxt and node_modules to ensure there are no caching issues.
Summary:You should be able to use
<span class="font-bold">test</span> anywhere in your app if your Tailwind CSS is set up as described above. If it’s not working, it’s likely a CSS import or content scanning issue, not a Nuxt UI override problem.
If you continue to have issues, please share your main.css and nuxt.config.ts for further troubleshooting Theme.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@398518214532923400> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
@kapa.ai I'm in a mono repo. All apps are into the packages folder. Here I have a frontend/admin directory for my application and I also have a shared/ui directory for my components
I added main.css into frontend/admin/app/assets/css/main.css
this is the code:
@import "tailwindcss";
@import "@nuxt/ui";
@layer base {
*,
::after,
::before,
::backdrop,
::file-selector-button {
border-color: var(--color-gray-200, currentcolor);
}
}
html { @apply w-full min-h-full bg-gradient-to-br; }
html:not(.dark) { @apply from-neutral-50 to-neutral-100 text-neutral-800; }
html.dark { @apply from-neutral-900 to-neutral-950 text-neutral-200; }
.title-lg { @apply text-3xl font-semibold leading-tight tracking-tight; }
.title { @apply text-2xl font-semibold leading-tight tracking-tight; }
.title-sm { @apply text-xl font-semibold leading-tight tracking-tight; }
.subtitle-lg { @apply text-lg font-medium leading-snug; }
.subtitle { @apply text-base font-medium leading-snug; }
.subtitle-sm { @apply text-sm font-medium leading-snug; }
.body { @apply text-base font-normal leading-relaxed; }
.body-sm { @apply text-sm font-normal leading-relaxed; }
.caption { @apply text-xs font-medium leading-normal; }
.striped-table tbody tr:nth-child(even) {
@apply bg-neutral-50 dark:bg-neutral-800/30;
}
And this is the nuxt config:
import tailwindcss from '@tailwindcss/vite'
import { i18nConfig } from '../../shared/config/i18n.config'
const isProduction = process.env.NODE_ENV === 'production'
export default defineNuxtConfig({
extends: [
'../../shared/ui',
'../../shared/services',
'../../shared/utils',
'../../shared/models',
],
modules: isProduction ? ['@nuxt/ui', '@nuxtjs/i18n'] : ['@nuxt/eslint', '@nuxt/ui', '@nuxtjs/i18n'],
imports: {
dirs: [
'./constants/app',
],
},
devtools: { enabled: true },
css: ['~/assets/css/main.css'],
vite: {
plugins: [
tailwindcss(),
],
},
Let me check the knowledge base for you again. One moment! :books:
----------------------
Based on your setup and the knowledge sources, here are some important points and recommendations for using Tailwind CSS and Nuxt UI v3 in a monorepo with shared components:
---
1. Tailwind Content Scanning in Monorepos
In a monorepo, especially when using Nuxt Layers and shared packages, Tailwind CSS v4 may not automatically scan all directories (like your shared/ui components). This can result in classes such as
Use the
font-bold not being included in the final CSS if they only appear in files outside your main app directory.
Solution:Use the
@source directive in your main.css to explicitly tell Tailwind where to look for class usage. For example, if your shared components are in ../../shared/ui/components, add:
This approach is confirmed to resolve similar issues in Nuxt monorepos and layered setups, ensuring Tailwind picks up all classes used in shared directories Nuxt Layers not processing CSS correctly from base layer.
---
2. No Need for tailwind.config.js
With Nuxt UI v3 and Tailwind v4, you should not use a tailwind.config.js file. All theming and design tokens should be handled via the @theme directive in your CSS Theme.
---
3. Vite Plugin Usage
You do not need to manually add the @tailwindcss/vite plugin in your vite.plugins array. Nuxt UI and Tailwind integration is handled automatically when you import them in your CSS and add @nuxt/ui to your modules. Manual addition may cause conflicts or unexpected behavior Installation.
---
4. Summary of Steps
- Ensure your main.css imports Tailwind and Nuxt UI, and includes @source directives for all relevant directories.
- Remove any tailwind.config.js files.
- Do not manually add the Tailwind Vite plugin in your Nuxt config.
- Make sure your css array in nuxt.config.ts points to the correct CSS file.
---
If you follow these steps, Tailwind classes like font-bold should work everywhere, including in simple tags and shared components. If you still encounter issues, double-check the paths in your @source directives and ensure your dev server is restarted after changes Nuxt Layers not processing CSS correctly from base layer Theme.
If you need more help, please share the structure of your monorepo and the exact paths to your shared components.
----------------------
Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:
----------------------<@398518214532923400> Kapa.ai is still learning and improving, please let me know how I did by reacting below.