opencloud/.agents/skills/naive-ui-ssr/SKILL.md

name, description, metadata

name	description	metadata
naive-ui-ssr	Server-Side Rendering configuration and best practices for Naive UI. Invoke when user needs to implement SSR with Naive UI in Nuxt.js, Vitepress, Vite SSG/SSE, or Webpack environments.	author version jiaiyan 1.0.0

Naive UI Server-Side Rendering (SSR)

Naive UI uses CSS-in-JS, which requires additional configuration when using Server-Side Rendering (SSR). This skill provides guidance for setting up SSR across different frameworks and build tools.

When to Use

Use this skill when:

• Nuxt.js integration: Setting up Naive UI in a Nuxt.js application
• Vitepress integration: Using Naive UI components in Vitepress documentation
• Vite SSG/SSE: Implementing static site generation or server-side rendering with Vite
• Webpack SSR: Configuring SSR with Webpack-based setups
• SSR optimization: Reducing SSR-rendered HTML size
• Troubleshooting SSR issues: Resolving common SSR-related problems

When to Invoke

Invoke this skill when:

• User asks about SSR setup with Naive UI
• User encounters SSR build failures or hydration issues
• User wants to optimize SSR performance
• User needs to configure Naive UI for Nuxt.js, Vitepress, or Vite SSR
• User sees CSS-related errors during SSR builds

Prerequisites

Critical Requirements

Before implementing SSR with Naive UI, ensure the following conditions are met:

1. css-render version: All direct and indirect references to @css-render/* and css-render packages must be version >=0.15.14

2. Single package resolution: Each @css-render/* and css-render package should resolve to a single target (no duplicate versions or copies)

Verifying Requirements

Check your lock file for duplicate css-render packages:

# For npm
npm ls css-render

# For pnpm
pnpm ls css-render

# For yarn
yarn why css-render

Resolving Duplicate Packages

If you find duplicate packages, use the resolution field in package.json:

{
  "resolutions": {
    "css-render": "^0.15.14",
    "@css-render/vue3-ssr": "^0.15.14"
  }
}

For pnpm, use pnpm.overrides:

{
  "pnpm": {
    "overrides": {
      "css-render": "^0.15.14",
      "@css-render/vue3-ssr": "^0.15.14"
    }
  }
}

Basic Usage

Nuxt.js Integration

For Nuxt.js applications, refer to the dedicated Nuxt.js documentation:

# See Nuxt.js specific guide
# Path: docs/nuxtjs.md

Vitepress Integration

For Vitepress documentation sites:

# See Vitepress specific guide
# Path: docs/vitepress.md

Vite SSG/SSE

For Vite-based static site generation:

# See Vite SSG/SSE specific guide
# Path: docs/vite-ssge.md

Webpack SSR Example

Reference implementation available at:

• GitHub: naive-ui-vite-ssr
• Playground: naive-ui/playground/ssr

API Reference

Inline Theme Optimization

Prop	Type	Default	Description
inline-theme-disabled	boolean	false	Disable inline theme styles on components to reduce SSR HTML size

Usage with n-config-provider

<template>
  <n-config-provider inline-theme-disabled>
    <n-button>Optimized for SSR</n-button>
  </n-config-provider>
</template>

Common Patterns

SSR-Optimized Configuration

<template>
  <n-config-provider
    inline-theme-disabled
    :theme="theme"
  >
    <n-global-style />
    <router-view />
  </n-config-provider>
</template>

<script setup>
import { ref } from 'vue'
import { darkTheme } from 'naive-ui'

const theme = ref(null)
</script>

Nuxt.js Plugin Setup

// plugins/naive-ui.ts
import { setup } from '@css-render/vue3-ssr'
import { defineNuxtPlugin } from '#app'

export default defineNuxtPlugin((nuxtApp) => {
  if (process.server) {
    const { collect } = setup(nuxtApp.vueApp)
    const originalRenderMeta = nuxtApp.ssrContext?.renderMeta
    
    nuxtApp.ssrContext = nuxtApp.ssrContext || {}
    nuxtApp.ssrContext.renderMeta = () => {
      if (!originalRenderMeta) {
        return {
          headTags: collect()
        }
      }
      const originalMeta = originalRenderMeta()
      if (originalMeta && typeof originalMeta === 'object') {
        return {
          ...originalMeta,
          headTags: `${originalMeta.headTags || ''}${collect()}`
        }
      }
      return originalMeta
    }
  }
})

Vite SSR Entry Setup

// server-entry.ts
import { createSSRApp } from 'vue'
import { setup } from '@css-render/vue3-ssr'
import App from './App.vue'

export function createApp() {
  const app = createSSRApp(App)
  
  if (import.meta.env.SSR) {
    setup(app)
  }
  
  return { app }
}

Collecting CSS in Vite SSR

// server.ts
import { renderToString } from 'vue/server-renderer'
import { createApp } from './server-entry'

async function render(url: string) {
  const { app } = createApp()
  
  const ctx: { modules?: string[] } = {}
  const html = await renderToString(app, ctx)
  
  // CSS will be collected automatically by css-render
  return html
}

Known Issues

The following components have known issues in SSR environments. Avoid using them if possible:

Component	Issue	Status
n-scrollbar	SSR rendering issues	Fixed in Vue >= 3.2.36
n-data-table	SSR rendering issues	Fixed in Vue >= 3.2.36
n-anchor	SSR rendering issues	Pending fix
n-avatar-group	SSR rendering issues	Pending fix
n-watermark	SSR rendering issues	Pending fix
n-affix	SSR rendering issues	Pending fix
n-transfer	SSR rendering issues	Pending fix

Workaround for Known Issues

<template>
  <ClientOnly>
    <n-scrollbar>
      <n-data-table :data="data" />
    </n-scrollbar>
  </ClientOnly>
</template>

<script setup>
import { ClientOnly } from '#components'

const data = ref([])
</script>

Best Practices

1. Verify css-render versions: Always check that all css-render packages are >= 0.15.14 and deduplicated

   npm ls css-render
   

2. Use inline-theme-disabled: Enable this option to reduce SSR HTML size

   <n-config-provider inline-theme-disabled>
     <App />
   </n-config-provider>
   

3. Wrap problematic components: Use ClientOnly wrapper for components with known SSR issues

   <ClientOnly>
     <n-watermark content="Draft" />
   </ClientOnly>
   

4. Check Vue version: Ensure Vue >= 3.2.36 for n-scrollbar and n-data-table SSR support

5. Test hydration: Verify that client-side hydration works correctly

   // Check for hydration mismatches in console
   

6. Use resolutions field: Prevent duplicate css-render packages

   {
     "resolutions": {
       "css-render": "^0.15.14"
     }
   }
   

7. Follow framework-specific guides: Use the appropriate guide for your framework

   • Nuxt.js: See nuxtjs documentation
   • Vitepress: See vitepress documentation
   • Vite SSG/SSE: See vite-ssge documentation

8. Reference examples: Check official examples for implementation patterns

   • Vite SSR: naive-ui-vite-ssr
   • Webpack SSR: playground/ssr

Troubleshooting

Common Error: CSS Not Applied

Problem: Styles are missing after SSR hydration

Solution: Ensure css-render is properly configured for SSR

import { setup } from '@css-render/vue3-ssr'

if (import.meta.env.SSR) {
  setup(app)
}

Common Error: Hydration Mismatch

Problem: Vue hydration mismatch warnings in console

Solution:

1. Check for browser-only APIs in setup code
2. Wrap problematic components in ClientOnly
3. Ensure data is consistent between server and client

Common Error: Duplicate css-render Packages

Problem: Build fails or styles break due to multiple css-render versions

Solution: Add resolutions to package.json

{
  "resolutions": {
    "css-render": "^0.15.14",
    "@css-render/vue3-ssr": "^0.15.14"
  }
}

Related Skills

• n-config-provider: Global configuration for SSR optimization
• naive-ui-theming: Theme customization in SSR
• naive-ui-dark-mode: Dark mode with SSR considerations