菜单
Install, register and wire up the @kilivi-dev/payloadcms-theme-management plugin in a Payload CMS v3 + Next.js App Router project — collection tab vs standalone collection, live preview, cache revalidation, and rendering the resolved theme on the front-end.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use the admin-side and programmatic theming tools in @kilivi-dev/payloadcms-theme-management — generate a full light/dark palette from one brand colour or a logo, run a WCAG accessibility audit of the palette with one-click fixes, and export the theme as W3C design tokens (JSON) or Tailwind v4 @theme / v3 config.
Add front-end (visitor-facing) theme controls from @kilivi-dev/payloadcms-theme-management — the ColorModeToggle (light/dark/auto with a View Transitions ripple animation) and the ThemeSwitcher (runtime theme-preset switching). Use when a site needs a dark-mode button or a theme picker for end users.
Add theme-aware colour and appearance controls to any Payload collection, block or global using the out-of-the-box helpers from @kilivi-dev/payloadcms-theme-management (createColorGroup, createColorField), and resolve the stored values to CSS on the front-end with resolveColorValue.
Wire up and debug live theme preview for @kilivi-dev/payloadcms-theme-management — the native Payload Live Preview iframe (with mobile/tablet/desktop breakpoints), the in-admin device + light/dark preview panels, and the ThemeLivePreviewSync client component that applies theme CSS live without a full save.
Use when working with Payload projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
Next.js 16 with App Router, Server Components, Server Actions, Cache Components. Use for React 19.2 apps, SSR, or encountering async params, proxy.ts migration, use cache errors.
| name | theme-management-setup |
| description | Install, register and wire up the @kilivi-dev/payloadcms-theme-management plugin in a Payload CMS v3 + Next.js App Router project — collection tab vs standalone collection, live preview, cache revalidation, and rendering the resolved theme on the front-end. |
Use this skill when adding the @kilivi-dev/payloadcms-theme-management plugin to a
Payload v3 project, or when debugging why a configured theme is not showing on the
front-end.
In payload.config.ts:
import { themeManagementPlugin } from '@kilivi-dev/payloadcms-theme-management'
export default buildConfig({
plugins: [
themeManagementPlugin({
// Adds an "Appearance Settings" tab to an existing collection…
targetCollection: 'site-settings',
useStandaloneCollection: false,
// …or set useStandaloneCollection: true to create a dedicated collection
// standaloneCollectionSlug: 'appearance-settings',
includeColorModeToggle: true, // light / dark / auto toggle
includeCustomCSS: true, // raw CSS escape hatch
enableAdvancedFeatures: true, // animation level etc.
// Native Payload Live Preview (iframe). `true` enables sensible defaults,
// including mobile/tablet/desktop breakpoints out of the box.
livePreview: true,
// Append project-specific controls inside the themeConfiguration group:
customThemeConfigurationFields: [/* Field[] */],
customThemeConfigurationSections: [
{ label: { en: 'Booking Widget', cs: 'Rezervační widget' }, fields: [/* … */] },
],
}),
],
})
Key options (full list in ThemeManagementPluginOptions, src/types.ts):
targetCollection / useStandaloneCollection / standaloneCollectionSlugthemePresets, defaultThemelivePreview?: boolean | ThemeManagementLivePreviewOptionscacheRevalidation?: boolean | ThemeManagementCacheRevalidationOptionscustomThemeConfigurationFields / customThemeConfigurationSectionsAfter changing field components, regenerate the import map:
payload generate:importmap.
In the tenant/root layout (server component):
import { ServerThemeInjector } from '@kilivi-dev/payloadcms-theme-management/server'
import { resolveThemeConfiguration, ThemeProvider } from '@kilivi-dev/payloadcms-theme-management'
import { getThemeHtmlAttributes } from '@kilivi-dev/payloadcms-theme-management'
const settings = await fetchSiteSettings() // your own fetch
const themeConfig = resolveThemeConfiguration(settings?.themeConfiguration)
return (
<html {...getThemeHtmlAttributes(themeConfig)}>
<head>
<ServerThemeInjector themeConfiguration={settings?.themeConfiguration} />
</head>
<body>
<ThemeProvider>{children}</ThemeProvider>
</body>
</html>
)
ServerThemeInjector emits the <style> with all CSS custom properties +
html[data-*] effect selectors at SSR time (no flash). getThemeHtmlAttributes
sets data-theme, data-theme-mode, data-effect-style, data-card-style, etc.
To fetch the stored config from a client/edge context use fetchThemeConfiguration
(supports collection or global via useGlobal, plus tenantSlug, locale, draft).
unstable_cache)From @kilivi-dev/payloadcms-theme-management/server:
createCachedThemeFetcher, revalidateThemeCache, getThemeCacheTag.The plugin can also inject a Payload endpoint (default /api/theme/revalidate,
optional secret) when cacheRevalidation is enabled.
ServerThemeInjector not in <head>, or
data-* attributes missing on <html> (use getThemeHtmlAttributes).payload generate:importmap../fields/* subpath so generate:importmap stays server-safe.Related: [theme-color-fields], [theme-live-preview].