fix: make alias can be overridden properly

e2e/docs/.vuepress/config.ts

@@ -83,4 +83,13 @@ export default defineUserConfig({
   },
 
   plugins: [fooPlugin],
+
+  // The alias entries are intentionally ordered by key length to ensure
+  // that more specific aliases (e.g., '@dir/a.js') take precedence over
+  // less specific ones (e.g., '@dir'). Do not reorder these entries.
+  alias: {
+    '@dir/a.js': path.resolve(__dirname, '../../modules/dir2/a.js'),
+    '@dir': path.resolve(__dirname, '../../modules/dir1'),
+    '@dir/b.js': path.resolve(__dirname, '../../modules/dir2/b.js'),
+  },
 })

e2e/docs/hooks/alias/dir.md

@@ -0,0 +1,5 @@
+<p id="result">{{result}}</p>
+
+<script setup>
+import { result } from '@dir/c.js'
+</script>

e2e/docs/hooks/alias/override.md

@@ -0,0 +1,7 @@
+<p id="a">{{aResult}}</p>
+<p id="b">{{bResult}}</p>
+
+<script setup>
+import { result as aResult } from '@dir/a.js'
+import { result as bResult } from '@dir/b.js'
+</script>

e2e/modules/dir1/a.js

@@ -0,0 +1 @@
+export const result = 'dir1 > a'

e2e/modules/dir1/b.js

@@ -0,0 +1 @@
+export const result = 'dir1 > b'

e2e/modules/dir1/c.js

@@ -0,0 +1 @@
+export const result = 'dir1 > c'

e2e/modules/dir2/a.js

@@ -0,0 +1 @@
+export const result = 'dir2 > a'

e2e/modules/dir2/b.js

@@ -0,0 +1 @@
+export const result = 'dir2 > b'

e2e/tests/hooks/alias/dir.spec.ts

@@ -0,0 +1,6 @@
+import { expect, test } from '@playwright/test'
+
+test('should apply alias to subpath', async ({ page }) => {
+  await page.goto('hooks/alias/dir.html')
+  await expect(page.locator('#result')).toHaveText('dir1 > c')
+})

e2e/tests/hooks/alias/override.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from '@playwright/test'
+
+test('longer aliases should override shorter ones', async ({ page }) => {
+  await page.goto('hooks/alias/override.html')
+  await expect(page.locator('#a')).toHaveText('dir2 > a')
+  await expect(page.locator('#b')).toHaveText('dir2 > b')
+})

packages/bundler-vite/src/plugins/vuepressConfigPlugin.ts

@@ -25,16 +25,17 @@ const resolveAlias = async ({
   const aliasResult = await app.pluginApi.hooks.alias.process(app, isServer)
 
   aliasResult.forEach((aliasObject) => {
-    Object.entries(aliasObject).forEach(([key, value]) => {
-      alias[key] = value as string
-    })
+    Object.assign(alias, aliasObject)
   })
 
   return [
-    ...Object.keys(alias).map((item) => ({
-      find: item,
-      replacement: alias[item],
-    })),
+    ...Object.keys(alias)
+      // sort alias by length in descending order to ensure longer alias is handled first
+      .sort((a, b) => b.length - a.length)
+      .map((item) => ({
+        find: item,
+        replacement: alias[item],
+      })),
     ...(isServer
       ? []
       : [

packages/bundler-webpack/src/config/handleResolve.ts

@@ -14,17 +14,27 @@ export const handleResolve = async ({
   isServer: boolean
 }): Promise<void> => {
   // aliases
-  config.resolve.alias
-    .set('@source', app.dir.source())
-    .set('@temp', app.dir.temp())
-    .set('@internal', app.dir.temp('internal'))
+  const alias = {
+    '@source': app.dir.source(),
+    '@temp': app.dir.temp(),
+    '@internal': app.dir.temp('internal'),
+  }
 
-  // extensionAlias
-  config.resolve.extensionAlias.merge({
-    '.js': ['.js', '.ts'],
-    '.mjs': ['.mjs', '.mts'],
+  // plugin hook: alias
+  const aliasResult = await app.pluginApi.hooks.alias.process(app, isServer)
+
+  aliasResult.forEach((aliasObject) => {
+    Object.assign(alias, aliasObject)
   })
 
+  // set aliases
+  config.resolve.alias.merge(
+    Object.fromEntries(
+      // sort alias by length in descending order to ensure longer alias is handled first
+      Object.entries(alias).sort(([a], [b]) => b.length - a.length),
+    ),
+  )
+
   // extensions
   config.resolve.extensions.merge([
     '.js',
@@ -35,13 +45,9 @@ export const handleResolve = async ({
     '.json',
   ])
 
-  // plugin hook: alias
-  const aliasResult = await app.pluginApi.hooks.alias.process(app, isServer)
-
-  // set aliases
-  aliasResult.forEach((aliasObject) => {
-    Object.entries(aliasObject).forEach(([key, value]) => {
-      config.resolve.alias.set(key, value as string)
-    })
+  // extensionAlias
+  config.resolve.extensionAlias.merge({
+    '.js': ['.js', '.ts'],
+    '.mjs': ['.mjs', '.mts'],
   })
 }

packages/core/src/pluginApi/createPluginApiRegisterHooks.ts

@@ -1,4 +1,4 @@
-import type { PluginApi } from '../types/index.js'
+import type { AliasHook, DefineHook, PluginApi } from '../types/index.js'
 import { normalizeAliasDefineHook } from './normalizeAliasDefineHook.js'
 import { normalizeClientConfigFileHook } from './normalizeClientConfigFileHook.js'
 
@@ -30,14 +30,14 @@ export const createPluginApiRegisterHooks =
         if (alias) {
           hooks.alias.add({
             pluginName,
-            hook: normalizeAliasDefineHook(alias),
+            hook: normalizeAliasDefineHook<AliasHook>(alias),
           })
         }
 
         if (define) {
           hooks.define.add({
             pluginName,
-            hook: normalizeAliasDefineHook(define),
+            hook: normalizeAliasDefineHook<DefineHook>(define),
           })
         }
 

packages/core/src/pluginApi/normalizeAliasDefineHook.ts

@@ -1,12 +1,12 @@
 import { isFunction } from '@vuepress/shared'
-import type { AliasDefineHook } from '../types/index.js'
+import type { AliasHook, DefineHook } from '../types/index.js'
 
 /**
  * Normalize alias and define hook
  *
  * @internal
  */
 export const normalizeAliasDefineHook =
-  (hook: AliasDefineHook['exposed']): AliasDefineHook['normalized'] =>
+  <T extends AliasHook | DefineHook>(hook: T['exposed']): T['normalized'] =>
   async (app, isServer) =>
     isFunction(hook) ? hook(app, isServer) : hook

packages/core/src/types/pluginApi/hooks.ts

@@ -41,8 +41,15 @@ export type ClientConfigFileHook = Hook<
   (app: App) => Promise<string>
 >
 
-// alias and define hook
-export type AliasDefineHook = Hook<
+// alias hook
+export type AliasHook = Hook<
+  | Record<string, string>
+  | ((app: App, isServer: boolean) => PromiseOrNot<Record<string, string>>),
+  (app: App, isServer: boolean) => Promise<Record<string, string>>
+>
+
+// define hook
+export type DefineHook = Hook<
   | Record<string, unknown>
   | ((app: App, isServer: boolean) => PromiseOrNot<Record<string, unknown>>),
   (app: App, isServer: boolean) => Promise<Record<string, unknown>>
@@ -62,8 +69,8 @@ export interface Hooks {
   extendsPage: ExtendsHook<Page>
   extendsBundlerOptions: ExtendsHook<BundlerOptions>
   clientConfigFile: ClientConfigFileHook
-  alias: AliasDefineHook
-  define: AliasDefineHook
+  alias: AliasHook
+  define: DefineHook
 }
 
 /**

packages/core/tests/pluginApi/normalizeAliasDefineHook.spec.ts

@@ -1,6 +1,6 @@
 import { path } from '@vuepress/utils'
 import { expect, it, vi } from 'vitest'
-import type { AliasDefineHook, Bundler } from '../../src/index.js'
+import type { AliasHook, Bundler, DefineHook } from '../../src/index.js'
 import { createBaseApp, normalizeAliasDefineHook } from '../../src/index.js'
 
 const app = createBaseApp({
@@ -9,13 +9,19 @@ const app = createBaseApp({
   bundler: {} as Bundler,
 })
 
+it('should wrap object with a function', async () => {
+  const rawHook: AliasHook['exposed'] = {
+    foo: 'bar',
+  }
+  const normalizedHook = normalizeAliasDefineHook(rawHook)
+  expect(await normalizedHook(app, true)).toEqual({ foo: 'bar' })
+})
+
 it('should keep function as is', async () => {
-  const rawHook: AliasDefineHook['exposed'] = vi.fn(
-    (_app, isServer: boolean) => ({
-      foo: 'bar',
-      isServer,
-    }),
-  )
+  const rawHook: DefineHook['exposed'] = vi.fn((_app, isServer: boolean) => ({
+    foo: 'bar',
+    isServer,
+  }))
   const normalizedHook = normalizeAliasDefineHook(rawHook)
   expect(await normalizedHook(app, true)).toEqual({
     foo: 'bar',
@@ -24,11 +30,3 @@ it('should keep function as is', async () => {
   expect(rawHook).toHaveBeenCalledTimes(1)
   expect(rawHook).toHaveBeenCalledWith(app, true)
 })
-
-it('should wrap object with a function', async () => {
-  const rawHook: AliasDefineHook['exposed'] = {
-    foo: 'bar',
-  }
-  const normalizedHook = normalizeAliasDefineHook(rawHook)
-  expect(await normalizedHook(app, true)).toEqual({ foo: 'bar' })
-})