Feature: return an object with id keys and style values for vue3-ssr

[jbmolle]

Hi,

Would it be possible to have a function similar to collect in vue3-ssr but instead of returning a joined string of all the styles, it would be an object { [id]: styleString }?
Nuxt v3.7.0 has just updated how they manage SSR Head with unhead. Before we could return an object { headTags: collect() } in nuxtApp.ssrContext.renderMeta. Now we are using useServerHead({ style: [xxx] }).

So to integrate NaiveUI with Nuxt, we were creating a plugin like this:

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

export default defineNuxtPlugin((nuxtApp) => {
  if (process.server) {
    const { collect } = setup(nuxtApp.vueApp)
    nuxtApp.ssrContext!.renderMeta = () => {
      return {
        headTags: collect(),
      }
    }
  }
})

But now, we have to do:

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

export default defineNuxtPlugin((nuxtApp) => {
    const { collect } = setup(nuxtApp.vueApp)
    useServerHead({
        style: () => {
            const stylesString = collect()
            const stylesArray = stylesString.split(/<\/style>/g).filter(style => style)
            return stylesArray.map((styleString: string) => {
                const match = styleString.match(/<style cssr-id="([^"]*)">([\s\S]*)/)
                if (match) {
                    const id = match[1]
                    return { 'cssr-id': id, children: match[2] }
                }
                return {}
            })
        }
    })
})

so it would be easier to have a function collectAsObject in setup that would return the map of ids and corresponding CSS styles.

[Groupguanfang]

2025-06-30.1.52.47.mov

This is a very good example, but I find that when used in conjunction with @nuxtjs/color-mode, server-side rendering still flashes.
I explored for a long time and finally came up with an final solution for naive ui + @nuxtjs/color-mode:

Firstly: set colorMode.storage to cookie in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: [ '@nuxtjs/color-mode'],
  colorMode: {
    // Set this to `cookie` ✨
    storage: 'cookie',
  },
})

Because the cookie will send as a http headers Cookie when the browser requesting the main html:

This way, when you use the useColorMode() hook on the server, it will return the correct preference based on the cookie in the request header like this:

if (import.meta.env.SSR) {
  const colorMode = useColorMode()
  // It is the right current color mode read from client cookie!
  const currentMode = colorMode.preference
}

But this is far from over: in the @nuxtjs/color-mode package, colorMode.preference defaults to three values: dark, light, and system. Imagine, when the client sends us the system, how do we know what color mode the client system is currently in?

The answer is obvious: we need another cookie to let the client send our server the current client default color pattern, so that we can make further judgments on the server to avoid hydration errors. Let's define this cookie name first:

const systemPreferenceCookieName = 'nuxt-sys-color-mode'

The method of determining the server is also very simple: nuxt provides a useRequestEvent() hook, which is used to obtain the request context object of the current server from H3:

const systemPreferenceCookieName = 'nuxt-sys-color-mode'

if (import.meta.env.SSR) {
  const colorMode = useColorMode()
  const event = useRequestEvent()
  const cookie = event?.headers.get('cookie') || ''
  const systemPreferenceCookieFromServerHeader: 'dark' | 'light' = cookie.split(';').find(c => c.trim().startsWith(`${systemPreferenceCookieName}=`))?.trim().split('=')[1].trim()

  // We then judge based on colorMode and our custom cookies:
  // When `colorMode.preference` is `system`, 
  // we use our own custom default color mode values passed from the client
  if (colorMode.preference === 'system') {
    theme.value = systemPreferenceCookieFromServerHeader === 'dark' ? darkTheme : null
  }
  // Else, we judge according to `colorMode.preference`
  else {
    theme.value = colorMode.preference === 'dark' ? darkTheme : null
  }
}

At this point we have finished our work on the server; next we should write the client. Here I used the useCookie and useEventListener auxiliary hooks in @vueuse/nuxt:

import type { BuiltInGlobalTheme } from 'naive-ui/es/themes/interface'
import { darkTheme } from 'naive-ui'

const systemPreferenceCookieName = 'nuxt-sys-color-mode'

if (!import.meta.env.SSR) {
  const theme = ref<BuiltInGlobalTheme | null>(null)
  const systemPreferenceCookie = useCookie(systemPreferenceCookieName)
  const mediaQueryList = window.matchMedia('(prefers-color-scheme: dark)')

  function detectSystemTheme() {
    if (colorMode.preference === 'system') {
      const isDark = mediaQueryList.matches
      theme.value = isDark ? darkTheme : null
      systemPreferenceCookie.value = isDark ? 'dark' : 'light'
    }
    else {
      theme.value = colorMode.preference === 'dark' ? darkTheme : null
      systemPreferenceCookie.value = colorMode.preference
    }
  }

  // Watch when the color mode is changed
  watch(() => colorMode, detectSystemTheme, { immediate: true })
  // MediaQueryList also extend from EventTarget, 
  // we can directly using `useEventListener` hook
  useEventListener(mediaQueryList, 'change', detectSystemTheme)
}

Finally, we can integrate the whole logic above into a convenient hook, which I call useUiTheme() here, you can copy it to composables folder in your nuxt + naive ui + @nuxtjs/color-mode project:

import type { BuiltInGlobalTheme } from 'naive-ui/es/themes/interface'
import { darkTheme } from 'naive-ui'

const systemPreferenceCookieName = 'nuxt-sys-color-mode'

export interface UseUiThemeReturn {
  /** Current Naive UI theme object. */
  theme: Ref<BuiltInGlobalTheme | null>
}

/**
 * Get current UI theme with `@nuxtjs/color-mode`.
 *
 * @example
 * In `app.vue` you can use `useUiTheme` to get the current UI theme and pass it to `NConfigProvider` to make it work:
 *
 * ```html
 * <script setup lang="ts">
 * const { theme } = useUiTheme()
 * </script>
 *
 * <template>
 *  <NConfigProvider :theme="theme">
 *    <NuxtPage />
 *  </NConfigProvider>
 * </template>
 * ```
 */
export function useUiTheme(): UseUiThemeReturn {
  const colorMode = useColorMode()
  const theme = ref<BuiltInGlobalTheme | null>(null)
  const systemPreferenceCookie = useCookie(systemPreferenceCookieName)

  // When colorMode is `system`, set the theme based on the custom system preference cookie, otherwise set the theme based on the colorMode.
  if (import.meta.env.SSR) {
    const event = useRequestEvent()
    const cookie = event?.headers.get('cookie') || ''
    const systemPreferenceCookieFromServerHeader = cookie.split(';').find(c => c.trim().startsWith(`${systemPreferenceCookieName}=`))?.trim().split('=')[1].trim()

    if (colorMode.preference === 'system') {
      theme.value = systemPreferenceCookieFromServerHeader === 'dark' ? darkTheme : null
    }
    else {
      theme.value = colorMode.preference === 'dark' ? darkTheme : null
    }
  }

  // When colorMode is `system`, detect the system theme and set the custom system preference cookie.
  if (!import.meta.env.SSR) {
    const mediaQueryList = window.matchMedia('(prefers-color-scheme: dark)')

    function detectSystemTheme() {
      if (colorMode.preference === 'system') {
        const isDark = mediaQueryList.matches
        theme.value = isDark ? darkTheme : null
        systemPreferenceCookie.value = isDark ? 'dark' : 'light'
      }
      else {
        theme.value = colorMode.preference === 'dark' ? darkTheme : null
        systemPreferenceCookie.value = colorMode.preference
      }
    }

    watch(() => colorMode, detectSystemTheme, { immediate: true })
    useEventListener(mediaQueryList, 'change', detectSystemTheme)
  }

  return {
    theme,
  }
}

[xbo1]

For Nuxt 4.0.3， the naive-ui.ts plugin should like this:

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

export default defineNuxtPlugin((nuxtApp) => {
  const { collect } = setup(nuxtApp.vueApp)
  if (import.meta.server) {
    useHead({
      style: () => {
        const stylesString = collect()
        const stylesArray = stylesString
          .split(/<\/style>/g)
          .filter((style) => style)
        return stylesArray.map((styleString: string) => {
          const match = styleString.match(/<style cssr-id="([^"]*)">([\s\S]*)/)
          if (match) {
            const id = match[1]
            return { 'cssr-id': id, innerHTML: match[2] }
          }
          return {}
        })
      }
    })
  }
});

because 'children' property has been removed in new version, use 'innerHTML' instead . see more: https://unhead.unjs.io/docs/typescript/head/guides/get-started/migration#removed-vmid-hid-children-body