element-plus-ssr

Element Plus Server-Side Rendering (SSR)

This skill provides comprehensive guidance for using Element Plus in SSR environments, including Nuxt.js and custom SSR setups.

When to Invoke

Invoke this skill when:

• User is building an SSR application with Element Plus
• User encounters hydration errors with Element Plus components
• User needs to configure Element Plus for Nuxt.js
• User asks about Teleport handling in SSR
• User needs to fix ID or z-index hydration mismatches

Nuxt.js Integration (Recommended)

For Nuxt.js users, use the official Element Plus Nuxt module:

Installation

npm install -D @element-plus/nuxt

Configuration

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@element-plus/nuxt'],
})

The module automatically handles all SSR-specific configurations.

Refer to Element Plus Nuxt documentation for more details.

Custom SSR Configuration

For custom SSR setups, you need to handle several special cases to avoid hydration errors.

1. Provide ID Injection

Element Plus generates unique IDs for components. In SSR, different IDs on server and client cause hydration errors.

Solution: Inject ID_INJECTION_KEY:

import { createApp } from 'vue'
import { ID_INJECTION_KEY } from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.provide(ID_INJECTION_KEY, {
  prefix: 1024,
  current: 0,
})

2. Provide ZIndex

Components like Dialog, Drawer, and Tooltip use z-index. Hydration errors can occur if z-index values differ between server and client.

Solution: Inject ZINDEX_INJECTION_KEY:

import { createApp } from 'vue'
import { ZINDEX_INJECTION_KEY } from 'element-plus'
import App from './App.vue'

const app = createApp(App)
app.provide(ZINDEX_INJECTION_KEY, { current: 0 })

3. Handle Teleports

Many Element Plus components use Vue's Teleport internally:

• ElDialog
• ElDrawer
• ElTooltip
• ElDropdown
• ElSelect
• ElDatePicker
• ElPopover
• ElPopconfirm