Nuxt Integration
Integrate Nuvex UI into Nuxt with an SSR-safe base, correct style loading, and theme persistence before moving into deeper theming or layout patterns.
Before you start
- You already completed Installation or already have the minimum Nuxt setup working.
- Your Nuxt app already compiles with Nuvex UI and the base styles.
- You want to resolve real Nuxt integration before going deeper into theming or App Shell.
What this guide adds
Installation gets the minimum setup working. This guide adds the Nuxt-specific layer so theme, SSR, and initial render behavior stay aligned.
Nuxt plugin
Registers Nuvex UI through Nuxt's plugin lifecycle instead of treating the setup like a generic Vue entry file.
Style loading order
Confirms the order of styles.css, framework.scss, and app-level overrides inside nuxt.config.ts.
SSR theme persistence
Uses a cookie as the source of truth so the server can resolve the initial theme before hydration.
Client fallback
Keeps localStorage as a client-side fallback without depending on it as the only source of the theme.
Register the Nuxt plugin
Start from the Nuxt plugin file where the app mounts Nuvex UI. This is the integration point that later holds theme or storage-specific behavior.
app/plugins/nuvex-ui.ts
Load styles in nuxt.config.ts
In Nuxt, style order determines whether framework styles and your own overrides land in the correct cascade from the first render.
Load nuvex-ui/styles.css first, then nuvex-ui/framework.scss, and keep your app styles after both.
nuxt.config.ts
Persist the theme across SSR and client
If the initial theme only lives in localStorage, the server cannot know it before rendering. Use a cookie as the SSR source and keep the client fallback only for compatibility.
In this guide, the cookie is the source of truth for SSR. localStorage stays as a client-side fallback and legacy compatibility layer.
app/plugins/nuvex-ui.ts helpers
app/plugins/nuvex-ui.ts cookie + storage
Assemble the Nuxt integration
Now combine the plugin, cookie, and client-side reads in one place so the app starts with a coherent initial theme on both the server and the client.
With this base, the server can already resolve the initial theme and the client can preserve it without depending only on post-hydration updates.
app/plugins/nuvex-ui.ts
Verify the integration
Use this checklist to confirm the Nuxt integration is ready before moving into deeper theming guidance.
- The app compiles and mounts Nuvex UI from the Nuxt plugin.
- Base styles and framework styles apply from nuxt.config.ts in the correct order.
- The initial theme no longer depends only on localStorage.
- After a page reload, the theme persists without drifting between server and client.
- There is no obvious theme flash right after hydration.
Common pitfalls
These issues usually appear once a Nuxt setup moves beyond the minimum installation and are worth resolving before continuing with theming.
The theme changes after hydration
Verify that the server reads the theme from a cookie and that the client does not depend only on localStorage for the initial value.
Styles do not load in the expected order
Confirm that styles.css loads before framework.scss and that your app overrides load after both.
The theme does not persist between reloads
Check that the client updates the cookie and not only localStorage when the theme changes.
I need deeper theme customization
Move next into Theming Overview, Runtime Theme API, or a dedicated custom themes guide instead of stretching this integration page.
Recommended next steps
Once the Nuxt integration is stable, continue with the page that best matches your next decision about theme behavior, runtime control, or layout.