secondsky/claude-skills / plugins/maz-ui/skills/maz-ui
maz-ui
VerifiedMaz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/accessibility.md | markdown | 16.2 KB |
| references/cli.md | markdown | 10.8 KB |
| references/components-feedback.md | markdown | 19.1 KB |
| references/components-forms.md | markdown | 8.4 KB |
| references/components-layout.md | markdown | 17.8 KB |
| references/components-navigation.md | markdown | 19.5 KB |
| references/composables.md | markdown | 28.3 KB |
| references/directives.md | markdown | 17.0 KB |
| references/form-validation.md | markdown | 22.7 KB |
| references/icons.md | markdown | 14.9 KB |
| references/mcp.md | markdown | 13.6 KB |
| references/migration-v4.md | markdown | 21.0 KB |
| references/performance.md | markdown | 17.0 KB |
| references/plugins.md | markdown | 25.1 KB |
| references/resolvers.md | markdown | 26.2 KB |
| references/setup-nuxt.md | markdown | 26.0 KB |
| references/setup-vue.md | markdown | 21.7 KB |
| references/ssr-ssg.md | markdown | 13.9 KB |
| references/theming.md | markdown | 7.2 KB |
| references/translations.md | markdown | 20.1 KB |
| references/troubleshooting.md | markdown | 9.0 KB |
references/ssr-ssg.md
View on GitHub# Maz-UI SSR & SSG Guide
Complete guide to using Maz-UI with Server-Side Rendering (SSR) and Static Site Generation (SSG) in Nuxt applications.
## Overview
Maz-UI v4 is fully compatible with Nuxt 3's SSR and SSG modes, providing optimal performance through smart theme strategies, critical CSS injection, and hydration optimization.
**Key Features**:
- π Full SSR/SSG support
- π¨ Multiple theme strategies (hybrid, runtime, buildtime)
- β‘ Critical CSS for instant theming
- π Dark mode without flash
- π§ Hydration optimization
- π¦ Automatic code splitting
---
## Nuxt Module Installation
### Basic Setup
```bash
npm install @maz-ui/nuxt
```
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@maz-ui/nuxt'],
mazUi: {
theme: {
preset: 'maz-ui',
strategy: 'hybrid', // β
RECOMMENDED for SSR/SSG
},
}
})
```
---
## Theme Strategies
Maz-UI offers three theme strategies, each optimized for different use cases:
### Hybrid Strategy (Recommended)
**Best for**: SSR/SSG applications with runtime theme switching
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
preset: 'maz-ui',
strategy: 'hybrid', // β
OPTIMAL for SSR/SSG
darkModeStrategy: 'class' // or 'media'
}
}
})
```
**How it works**:
1. **Server**: Generates critical CSS based on user preferences (cookie)
2. **Client**: Injects critical CSS in `<head>` (instant theme)
3. **Hydration**: No flash, theme persists across page loads
4. **Runtime**: Full theme switching without page reload
**Critical CSS injection**:
```html
<!-- Server-rendered -->
<head>
<style data-maz-ui-critical>
:root {
--maz-color-primary: 220 100% 50%;
--maz-color-secondary: 220 14% 96%;
/* ... critical theme variables */
}
</style>
</head>
```
**Benefits**:
- β
Instant theme on server render
- β
No flash of unstyled content (FOUC)
- β
Runtime theme switching
- β
Dark mode toggle works instantly
- β
User preference persistence (cookie)
**Bundle Impact**: ~15KB runtime theme logic + critical CSS
---
### Build-time Strategy
**Best for**: Static sites with no runtime theme switching
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
preset: 'maz-ui',
strategy: 'buildtime', // β
SMALLEST bundle
}
}
})
```
**How it works**:
1. **Build**: All CSS variables pre-generated at build time
2. **Server/Client**: Static CSS loaded (no runtime logic)
3. **Theme switching**: NOT possible (requires full rebuild)
**Benefits**:
- β
Smallest bundle size (~5KB smaller than hybrid)
- β
Fastest initial load
- β
Perfect for static themes
- β No runtime theme switching
- β No dark mode toggle
**Use cases**:
- Marketing sites with fixed branding
- Documentation sites
- Landing pages
---
### Runtime Strategy
**Best for**: Apps with multiple theme presets and user preference
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
preset: 'maz-ui',
strategy: 'runtime', // β οΈ LARGER bundle
darkModeStrategy: 'class'
}
}
})
```
**How it works**:
1. **Server**: Minimal CSS (base styles only)
2. **Client**: Full theme logic loaded
3. **Runtime**: Complete theme switching (all presets available)
**Benefits**:
- β
Full runtime theme switching
- β
All theme presets available
- β
User preference persistence
- β οΈ Larger initial bundle (~20KB)
- β οΈ Possible FOUC on slow connections
**Use cases**:
- Apps with theme marketplace
- Multi-tenant applications
- User-customizable themes
---
## Dark Mode Strategies
### Class Strategy (Recommended)
Uses `class="dark"` on `<html>` element:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
darkModeStrategy: 'class' // β
RECOMMENDED
}
}
})
```
**How it works**:
```html
<!-- Light mode -->
<html>
<body>...</body>
</html>
<!-- Dark mode -->
<html class="dark">
<body>...</body>
</html>
```
**CSS**:
```css
:root {
--maz-color-bg: 255 255 255; /* white */
}
.dark {
--maz-color-bg: 20 20 20; /* dark gray */
}
```
**Benefits**:
- β
Full control over dark mode
- β
Works with JavaScript disabled
- β
Persists across page loads (cookie)
- β
No flash on page load
---
### Media Strategy
Uses `prefers-color-scheme` media query:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
darkModeStrategy: 'media'
}
}
})
```
**How it works**:
```css
:root {
--maz-color-bg: 255 255 255;
}
@media (prefers-color-scheme: dark) {
:root {
--maz-color-bg: 20 20 20;
}
}
```
**Benefits**:
- β
Automatic based on system preferences
- β
No JavaScript required
- β Cannot be toggled by user
- β Follows system preference only
---
## SSR-Specific Optimizations
### Critical CSS Injection
With **hybrid strategy**, critical CSS is injected during SSR:
```typescript
// plugins/maz-ui.server.ts (auto-generated by @maz-ui/nuxt)
export default defineNuxtPlugin((nuxtApp) => {
// Server-only plugin
if (import.meta.server) {
// Read user preference from cookie
const darkMode = useCookie('maz-ui-dark-mode').value === 'true'
// Inject critical CSS based on preference
nuxtApp.hook('app:rendered', (ctx) => {
const criticalCss = generateCriticalCss(darkMode)
ctx.renderContext.head.push(`
<style data-maz-ui-critical>
${criticalCss}
</style>
`)
})
}
})
```
**Result**: User sees correct theme instantly on server render.
---
### Hydration Prevention
Some Maz-UI components should only render on client to prevent hydration mismatches:
#### Client-Only Components
```vue
<template>
<!-- β
OPTIMAL: Use <ClientOnly> for client-specific components -->
<ClientOnly>
<MazDialogConfirm />
<MazToast />
<MazWaitOverlay />
</ClientOnly>
</template>
```
**Why?**:
- Dialog, Toast, Wait plugins use browser APIs (not available on server)
- Prevents hydration warnings
- Improves SSR performance
---
#### Conditional Rendering
```vue
<script setup lang="ts">
const isClient = ref(false)
onMounted(() => {
isClient.value = true
})
</script>
<template>
<!-- Only render on client after mount -->
<div v-if="isClient">
<MazCarousel :images="images" />
</div>
</template>
```
---
### Lazy Hydration
For heavy components, defer hydration until visible:
```vue
<template>
<!-- Lazy hydrate MazGallery when in viewport -->
<LazyMazGallery
:images="galleryImages"
@intersect="onIntersect"
/>
</template>
```
**Benefits**:
- β
Faster initial hydration
- β
Components hydrate when needed
- β
Reduces Time to Interactive (TTI)
---
## Static Site Generation (SSG)
### Prerender Routes
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
prerender: {
routes: [
'/',
'/about',
'/contact',
'/blog',
// Dynamic routes
'/blog/post-1',
'/blog/post-2'
]
}
},
mazUi: {
theme: {
strategy: 'buildtime' // β
OPTIMAL for SSG
}
}
})
```
---
### Crawl Links for Prerendering
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
prerender: {
crawlLinks: true, // Auto-discover routes
routes: ['/']
}
}
})
```
---
### Dynamic Routes from API
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
prerender: {
routes: async () => {
// Fetch dynamic routes from API
const posts = await $fetch('/api/posts')
return posts.map(post => `/blog/${post.slug}`)
}
}
}
})
```
---
## Performance Optimization for SSR/SSG
### Code Splitting
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
vite: {
build: {
rollupOptions: {
output: {
manualChunks: {
'maz-ui-forms': [
'maz-ui/components/MazInput',
'maz-ui/components/MazSelect',
'maz-ui/components/MazTextarea'
]
}
}
}
}
}
})
```
---
### Resource Hints
```vue
<!-- app.vue -->
<template>
<Head>
<!-- Preconnect to external resources -->
<Link rel="preconnect" href="https://fonts.googleapis.com" />
<!-- Preload critical assets -->
<Link
rel="preload"
href="/fonts/inter.woff2"
as="font"
type="font/woff2"
crossorigin
/>
</Head>
<NuxtPage />
</template>
```
---
### Inline Critical CSS
For **buildtime strategy**, inline critical CSS:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
experimental: {
inlineSSRStyles: true // β
Inline critical CSS
}
})
```
---
## Common SSR/SSG Issues
### Issue: Hydration Mismatch
**Error**: `Hydration node mismatch: client content does not match server-rendered HTML`
**Cause**: Component renders differently on server vs client
**Solution**:
```vue
<template>
<!-- β WRONG: window is undefined on server -->
<div>Window width: {{ window.innerWidth }}</div>
<!-- β
CORRECT: Use onMounted for client-only logic -->
<div>Window width: {{ windowWidth }}</div>
</template>
<script setup lang="ts">
const windowWidth = ref(0)
onMounted(() => {
windowWidth.value = window.innerWidth
})
</script>
```
---
### Issue: Flash of Unstyled Content (FOUC)
**Cause**: Theme CSS loads after initial render
**Solution**: Use **hybrid strategy** with critical CSS:
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
strategy: 'hybrid', // β
Prevents FOUC
darkModeStrategy: 'class'
}
}
})
```
---
### Issue: Dark Mode Flash
**Cause**: Server renders light mode, client switches to dark
**Solution 1: Hybrid strategy** (reads cookie on server):
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
mazUi: {
theme: {
strategy: 'hybrid', // β
Server reads cookie
darkModeStrategy: 'class'
}
}
})
```
**Solution 2: Blocking script** (for runtime strategy):
```vue
<!-- app.vue -->
<template>
<Head>
<Script>
(function() {
const darkMode = document.cookie.includes('maz-ui-dark-mode=true')
if (darkMode) {
document.documentElement.classList.add('dark')
}
})()
</Script>
</Head>
</template>
```
---
### Issue: Client-Only Plugins Not Working
**Cause**: Plugin runs on server where browser APIs don't exist
**Solution**: Mark plugin as client-only:
```typescript
// plugins/client-only.client.ts (note .client suffix)
export default defineNuxtPlugin(() => {
// This only runs on client
const toast = useToast()
return {
provide: {
toast
}
}
})
```
---
## SSR/SSG Checklist
### Pre-Deployment
- [ ] **Theme strategy** chosen (hybrid recommended for SSR)
- [ ] **Dark mode strategy** configured (class recommended)
- [ ] **Client-only components** wrapped in `<ClientOnly>`
- [ ] **Hydration mismatches** resolved (no server/client differences)
- [ ] **Critical CSS** inlined (hybrid strategy)
- [ ] **Resource hints** added (preconnect, preload)
- [ ] **Code splitting** configured (manual chunks for large components)
- [ ] **SSG routes** prerendered (if using SSG)
- [ ] **No FOUC** verified (critical CSS loaded)
- [ ] **No dark mode flash** verified (server reads cookie)
---
## Advanced SSR Patterns
### Server-Side Data Fetching
```vue
<script setup lang="ts">
// Fetch data on server
const { data: users } = await useFetch('/api/users')
</script>
<template>
<MazTable :rows="users" />
</template>
```
---
### Async Component with SSR
```vue
<script setup lang="ts">
const MazCarousel = defineAsyncComponent({
loader: () => import('maz-ui/components/MazCarousel'),
delay: 200, // Show loading after 200ms
timeout: 3000 // Error after 3s
})
</script>
<template>
<Suspense>
<template #default>
<MazCarousel :images="images" />
</template>
<template #fallback>
<MazCircularProgressBar />
</template>
</Suspense>
</template>
```
---
### Conditional SSR Rendering
```vue
<template>
<!-- Render on server for SEO -->
<div v-if="$nuxt.ssrContext">
<h1>{{ post.title }}</h1>
<p>{{ post.excerpt }}</p>
</div>
<!-- Rich client experience -->
<div v-else>
<MazCardSpotlight>
<h1>{{ post.title }}</h1>
<MazAnimatedText>{{ post.excerpt }}</MazAnimatedText>
</MazCardSpotlight>
</div>
</template>
```
---
## Theme Strategy Comparison
| Feature | Hybrid | Build-time | Runtime |
|---------|--------|------------|---------|
| **Bundle Size** | ~15KB | ~10KB | ~25KB |
| **Critical CSS** | β
Yes | β
Yes | β No |
| **Theme Switching** | β
Yes | β No | β
Yes |
| **Dark Mode Toggle** | β
Yes | β No | β
Yes |
| **FOUC Prevention** | β
Yes | β
Yes | β οΈ Partial |
| **SSR Performance** | βββββ | βββββ | βββ |
| **SSG Performance** | βββββ | βββββ | βββ |
| **Use Case** | SSR/SSG apps | Static sites | Multi-theme apps |
---
## Related Documentation
- **[Setup Nuxt](./setup-nuxt.md)** - Nuxt module configuration
- **[Theming](./theming.md)** - Theme customization
- **[Performance](./performance.md)** - Bundle optimization
- **[Composables](./composables.md)** - useTheme, useTranslations
- **[Troubleshooting](./troubleshooting.md)** - Common SSR errors
---
## External Resources
- **[Nuxt SSR](https://nuxt.com/docs/guide/concepts/rendering)** - Official Nuxt SSR guide
- **[Nuxt SSG](https://nuxt.com/docs/guide/concepts/rendering#static-site-generation)** - Static site generation
- **[Critical CSS](https://web.dev/extract-critical-css/)** - Web.dev guide
- **[Hydration](https://nuxt.com/docs/getting-started/data-fetching#clientonly-component)** - Nuxt hydration docs
---
**SSR/SSG Version**: Maz-UI v4.9.3 + Nuxt 4
**Last Updated**: 2026-08-03
::: tip Hybrid Strategy Recommended
For SSR/SSG applications, use `strategy: 'hybrid'` for optimal performance, instant theming, and runtime flexibility.
:::
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |