feat(core): add userStyle option to ensure highest css priority (close #1110) (#1695)

Mister-Hope · meteorlxy · web-flow · commit 071cc2156ccb · 2026-05-08T14:08:49.000+08:00
Co-authored-by: Xinyu Liu &lt;meteor.lxy@foxmail.com&gt;
diff --git a/packages/core/src/app/prepare/prepareClientConfigs.ts b/packages/core/src/app/prepare/prepareClientConfigs.ts
@@ -17,6 +17,7 @@ ${clientConfigFiles
     (filePath, index) => `import * as clientConfig${index} from '${filePath}'`,
   )
   .join('\n')}
+${app.options.userStyle ? `\nimport '${app.options.userStyle}'` : ''}
 
 export const clientConfigs = [
 ${clientConfigFiles.map((_, index) => `  clientConfig${index},`).join('\n')}
diff --git a/packages/core/src/app/resolveAppOptions.ts b/packages/core/src/app/resolveAppOptions.ts
@@ -45,6 +45,7 @@ export const resolveAppOptions = ({
   markdown = {},
   pagePatterns = ['**/*.md', '!.vuepress'],
   permalinkPattern = null,
+  userStyle = null,
   plugins = [],
   theme,
 }: AppConfig): AppOptions => {
@@ -76,6 +77,7 @@ export const resolveAppOptions = ({
     markdown,
     pagePatterns,
     permalinkPattern,
+    userStyle,
     plugins,
     theme,
   }
diff --git a/packages/core/src/app/resolveThemeInfo.ts b/packages/core/src/app/resolveThemeInfo.ts
@@ -14,6 +14,7 @@ export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {
     templateBuild: themeObject.templateBuild,
     templateBuildRenderer: themeObject.templateBuildRenderer,
     templateDev: themeObject.templateDev,
+    userStyle: themeObject.userStyle,
   }
 
   // return if current theme does not have a parent theme
@@ -30,5 +31,6 @@ export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {
       themeObject.templateBuildRenderer ??
       parentThemeInfo.templateBuildRenderer,
     templateDev: themeObject.templateDev ?? parentThemeInfo.templateDev,
+    userStyle: themeObject.userStyle ?? parentThemeInfo.userStyle,
   }
 }
diff --git a/packages/core/src/app/setupAppThemeAndPlugins.ts b/packages/core/src/app/setupAppThemeAndPlugins.ts
@@ -9,6 +9,7 @@ import { resolveThemeInfo } from './resolveThemeInfo.js'
 export const setupAppThemeAndPlugins = (app: App, config: AppConfig): void => {
   // recursively resolve theme info
   const themeInfo = resolveThemeInfo(app, app.options.theme)
+
   // set up app templates
   app.options.templateDev =
     config.templateDev ?? themeInfo.templateDev ?? app.options.templateDev
@@ -18,6 +19,11 @@ export const setupAppThemeAndPlugins = (app: App, config: AppConfig): void => {
     config.templateBuildRenderer ??
     themeInfo.templateBuildRenderer ??
     app.options.templateBuildRenderer
+
+  // set up user style
+  app.options.userStyle =
+    config.userStyle ?? themeInfo.userStyle ?? app.options.userStyle
+
   // use options plugins after theme plugins, allowing user to override theme plugins
   ;[...themeInfo.plugins, ...app.options.plugins]
     .flat()
diff --git a/packages/core/src/types/app/options.ts b/packages/core/src/types/app/options.ts
@@ -83,6 +83,11 @@ export interface AppConfigCommon extends Partial<SiteData> {
    */
   permalinkPattern?: string | null
 
+  /**
+   * Allow specifying user styles, which will be injected into client at the bottom
+   */
+  userStyle?: string | null
+
   /**
    * Vuepress bundler
    *
diff --git a/packages/core/src/types/theme.ts b/packages/core/src/types/theme.ts
@@ -51,6 +51,11 @@ export interface ThemeObject extends Omit<PluginObject, 'multiple'> {
    * Allow overriding default templateDev
    */
   templateDev?: string
+
+  /**
+   * Allow specifying user styles, which will be injected into client at the bottom
+   */
+  userStyle?: string
 }
 
 /**
@@ -76,4 +81,9 @@ export interface ThemeInfo {
    * Default dev template
    */
   templateDev?: string
+
+  /**
+   * Allow specifying user styles, which will be injected into client at the bottom
+   */
+  userStyle?: string
 }
diff --git a/packages/core/tests/__fixtures__/themes/func-user-style-child-inherit.js b/packages/core/tests/__fixtures__/themes/func-user-style-child-inherit.js
@@ -0,0 +1,6 @@
+import funcUserStyleParent from './func-user-style-parent.js'
+
+export default () => ({
+  name: 'theme-func-user-style-child-inherit',
+  extends: funcUserStyleParent(),
+})
diff --git a/packages/core/tests/__fixtures__/themes/func-user-style-child-override.js b/packages/core/tests/__fixtures__/themes/func-user-style-child-override.js
@@ -0,0 +1,7 @@
+import funcUserStyleParent from './func-user-style-parent.js'
+
+export default () => ({
+  name: 'theme-func-user-style-child-override',
+  extends: funcUserStyleParent(),
+  userStyle: 'child-user-style-override',
+})
diff --git a/packages/core/tests/__fixtures__/themes/func-user-style-parent.js b/packages/core/tests/__fixtures__/themes/func-user-style-parent.js
@@ -0,0 +1,4 @@
+export default () => ({
+  name: 'theme-func-user-style-parent',
+  userStyle: 'parent-user-style',
+})
diff --git a/packages/core/tests/__fixtures__/themes/obj-user-style-child-inherit.js b/packages/core/tests/__fixtures__/themes/obj-user-style-child-inherit.js
@@ -0,0 +1,6 @@
+import objUserStyleParent from './obj-user-style-parent.js'
+
+export default {
+  name: 'theme-obj-user-style-child-inherit',
+  extends: objUserStyleParent,
+}
diff --git a/packages/core/tests/__fixtures__/themes/obj-user-style-child-override.js b/packages/core/tests/__fixtures__/themes/obj-user-style-child-override.js
@@ -0,0 +1,7 @@
+import objUserStyleParent from './obj-user-style-parent.js'
+
+export default {
+  name: 'theme-obj-user-style-child-override',
+  extends: objUserStyleParent,
+  userStyle: 'child-user-style-override',
+}
diff --git a/packages/core/tests/__fixtures__/themes/obj-user-style-parent.js b/packages/core/tests/__fixtures__/themes/obj-user-style-parent.js
@@ -0,0 +1,4 @@
+export default {
+  name: 'theme-obj-user-style-parent',
+  userStyle: 'parent-user-style',
+}
diff --git a/packages/core/tests/app/resolveAppOptions.spec.ts b/packages/core/tests/app/resolveAppOptions.spec.ts
@@ -35,6 +35,7 @@ it('should create app options with default values', () => {
     open: false,
     pagePatterns: ['**/*.md', '!.vuepress'],
     permalinkPattern: null,
+    userStyle: null,
     templateDev: path.normalize(
       require.resolve('@vuepress/client/templates/dev.html'),
     ),
diff --git a/packages/core/tests/app/resolveThemeInfo.spec.ts b/packages/core/tests/app/resolveThemeInfo.spec.ts
@@ -97,3 +97,43 @@ describe('extends', () => {
     })
   })
 })
+
+describe('userStyle', () => {
+  describe('should resolve userStyle for theme with no parent', () => {
+    THEME_ENTRY_TYPES.forEach((item) => {
+      it(item, async () => {
+        const themePath = fixtures(`themes/${item}-user-style-parent.js`)
+        const app = await createTestApp(themePath)
+        expect(resolveThemeInfo(app, app.options.theme).userStyle).toBe(
+          'parent-user-style',
+        )
+      })
+    })
+  })
+
+  describe('should resolve userStyle when child overrides parent', () => {
+    THEME_ENTRY_TYPES.forEach((item) => {
+      it(item, async () => {
+        const themePath = fixtures(
+          `themes/${item}-user-style-child-override.js`,
+        )
+        const app = await createTestApp(themePath)
+        expect(resolveThemeInfo(app, app.options.theme).userStyle).toBe(
+          'child-user-style-override',
+        )
+      })
+    })
+  })
+
+  describe('should resolve userStyle when child inherits from parent', () => {
+    THEME_ENTRY_TYPES.forEach((item) => {
+      it(item, async () => {
+        const themePath = fixtures(`themes/${item}-user-style-child-inherit.js`)
+        const app = await createTestApp(themePath)
+        expect(resolveThemeInfo(app, app.options.theme).userStyle).toBe(
+          'parent-user-style',
+        )
+      })
+    })
+  })
+})

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ ${clientConfigFiles`
`17`	`17`	(filePath, index) => `import * as clientConfig${index} from '${filePath}'`,
`18`	`18`	`)`
`19`	`19`	`.join('\n')}`
	`20`	+${app.options.userStyle ? `\nimport '${app.options.userStyle}'` : ''}
`20`	`21`
`21`	`22`	`export const clientConfigs = [`
`22`	`23`	${clientConfigFiles.map((_, index) => ` clientConfig${index},`).join('\n')}
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {`
`14`	`14`	`templateBuild: themeObject.templateBuild,`
`15`	`15`	`templateBuildRenderer: themeObject.templateBuildRenderer,`
`16`	`16`	`templateDev: themeObject.templateDev,`
	`17`	`+ userStyle: themeObject.userStyle,`
`17`	`18`	`}`
`18`	`19`
`19`	`20`	`// return if current theme does not have a parent theme`
`@@ -30,5 +31,6 @@ export const resolveThemeInfo = (app: App, theme: Theme): ThemeInfo => {`
`30`	`31`	`themeObject.templateBuildRenderer ??`
`31`	`32`	`parentThemeInfo.templateBuildRenderer,`
`32`	`33`	`templateDev: themeObject.templateDev ?? parentThemeInfo.templateDev,`
	`34`	`+ userStyle: themeObject.userStyle ?? parentThemeInfo.userStyle,`
`33`	`35`	`}`
`34`	`36`	`}`