feat(experimental): warn against non absolute aliases

Author: posva

packages/router/src/unplugin/codegen/generateAliasWarnings.ts

@@ -0,0 +1,24 @@
+import type { PrefixTree } from '../core/tree'
+
+/**
+ * Generates runtime warnings for aliases that are not absolute paths.
+ *
+ * @param tree - prefix tree to scan
+ *
+ * @internal
+ */
+export function generateAliasWarnings(tree: PrefixTree): string {
+  const warnings: string[] = []
+
+  for (const node of tree.getChildrenDeepSorted()) {
+    for (const alias of node.value.alias) {
+      if (!alias.startsWith('/')) {
+        warnings.push(
+          `console.warn('[vue-router] Alias "${alias}" for route "${node.value.fullPath}" must be absolute (start with "/"). Relative aliases are not supported in file-based routing.')`
+        )
+      }
+    }
+  }
+
+  return warnings.join('\n')
+}

packages/router/src/unplugin/codegen/generateRouteResolver.spec.ts

@@ -8,6 +8,7 @@ import {
 } from './generateRouteResolver'
 import { ImportsMap } from '../core/utils'
 import { ParamParsersMap } from './generateParamParsers'
+import { generateAliasWarnings } from './generateAliasWarnings'
 
 const DEFAULT_OPTIONS = resolveOptions({})
 let DEFAULT_STATE: Parameters<typeof generateRouteRecord>[0]['state'] = {
@@ -1344,5 +1345,42 @@ describe('generateRouteResolver', () => {
       expect(resolver).toMatch(/createFixedResolver\(\[[\s\S]*__route_0/)
       expect(resolver).toMatch(/createFixedResolver\(\[[\s\S]*__route_1/)
     })
+
+    it('warns on relative aliases', () => {
+      const tree = new PrefixTree(DEFAULT_OPTIONS)
+      const node = tree.insert('admin/users', 'admin/users.vue')
+      node.setCustomRouteBlock('admin/users.vue', { alias: ['users'] })
+
+      const warnings = generateAliasWarnings(tree)
+
+      expect(warnings).toContain('console.warn')
+      expect(warnings).toContain('Alias "users"')
+      expect(warnings).toContain('must be absolute')
+    })
+
+    it('does not warn on absolute aliases', () => {
+      const tree = new PrefixTree(DEFAULT_OPTIONS)
+      const node = tree.insert('users', 'users.vue')
+      node.setCustomRouteBlock('users.vue', { alias: ['/people'] })
+
+      const warnings = generateAliasWarnings(tree)
+
+      expect(warnings).toBe('')
+    })
+
+    it('warns on each relative alias individually', () => {
+      const tree = new PrefixTree(DEFAULT_OPTIONS)
+      const node = tree.insert('users', 'users.vue')
+      node.setCustomRouteBlock('users.vue', {
+        alias: ['people', '/members', 'folks'],
+      })
+
+      const warnings = generateAliasWarnings(tree)
+
+      expect(warnings).toContain('"people"')
+      expect(warnings).toContain('"folks"')
+      expect(warnings).not.toContain('"members"')
+      expect(warnings).not.toContain('"/members"')
+    })
   })
 })

packages/router/src/unplugin/core/context.ts

@@ -21,6 +21,7 @@ import { EditableTreeNode } from './extendRoutes'
 import { ts } from '../utils'
 import { generateRouteResolver } from '../codegen/generateRouteResolver'
 import { generateDuplicatedRoutesWarnings } from '../codegen/generateDuplicateRoutesWarnings'
+import { generateAliasWarnings } from '../codegen/generateAliasWarnings'
 import { type FSWatcher, watch as fsWatch } from 'chokidar'
 import {
   generateParamParsersTypesDeclarations,
@@ -297,6 +298,7 @@ export function createRoutesContext(options: ResolvedOptions) {
     }
 
     const routeDupsWarns = generateDuplicatedRoutesWarnings(routeTree)
+    const aliasWarns = generateAliasWarnings(routeTree)
 
     const hmr = ts`
 export function handleHotUpdate(_router, _hotUpdateCallback) {
@@ -326,7 +328,7 @@ if (import.meta.hot) {
   })
 }`
 
-    const newAutoResolver = `${imports}${routeDupsWarns}\n${missingParserErrors}${resolverCode}\n${hmr}`
+    const newAutoResolver = `${imports}${routeDupsWarns}\n${aliasWarns}\n${missingParserErrors}${resolverCode}\n${hmr}`
 
     // prepend it to the code
     return newAutoResolver