fix: route argument narrowing with experimental.typedPages (#4024)

Author: BobbieGoede

package.json

@@ -64,7 +64,7 @@
     "lint:fix": "eslint . --cache --fix",
     "lint:knip": "knip --workspace .",
     "test": "nuxt-module-build prepare && pnpm test:types && pnpm test:unit && pnpm test:e2e",
-    "test:types": "tsc --noEmit",
+    "test:types": "tsc --noEmit && pnpm --filter './specs/fixtures/**' test:types",
     "test:unit": "vitest run test -c vitest.config.test.ts",
     "test:e2e": "vitest run specs"
   },

pnpm-lock.yaml

@@ -21,7 +21,7 @@
     {
       "groupName": "all non-major dependencies",
       "groupSlug": "all-minor-patch",
-      "matchFileNames": ["package.json"],
+      "matchFileNames": ["package.json", "specs/fixtures/**/package.json"],
       "matchUpdateTypes": ["minor", "patch"],
       "lockFileMaintenance": {
         "enabled": true,

renovate.json

@@ -18,13 +18,34 @@ await setup({
 
 // @see reference https://github.com/nuxt/nuxt/blob/c55db28542d29fd912889985780af70b4bb2ee2e/test/typed-router.test.ts
 describe('`experimental.typedPages` undefined or enabled', async () => {
+  const buildDir = resolve(rootDir, '.nuxt/___experimental_typed_pages_spec_ts')
+
   test('generates route types', async () => {
-    const typedRouterDtsFile = resolve(rootDir, '.nuxt/___experimental_typed_pages_spec_ts/types/typed-router-i18n.d.ts')
-    const typedRouterDts = readFileSync(typedRouterDtsFile, 'utf-8')
+    const typedRouterDts = readFileSync(resolve(buildDir, 'types/typed-router-i18n.d.ts'), 'utf-8')
 
     // Check for the interface definition
     expect(typedRouterDts).toMatch(/export interface RouteNamedMapI18n \{/)
     // Check for the route definition (accommodates both single-line and multi-line formatting)
     expect(typedRouterDts).toMatch(/'category-slug':\s*RouteRecordInfo<\s*'category-slug',\s*'\/category\/:slug\(\)',\s*\{\s*slug:\s*ParamValue<true>\s*\},\s*\{\s*slug:\s*ParamValue<false>\s*\}/)
+
+    // All occurrences must be renamed, or the interface merges with the one
+    // from Nuxt's typed-router.d.ts and pollutes `RouteMap` (#3962)
+    expect(typedRouterDts).not.toMatch(/\bRouteNamedMap\b/)
+    expect(typedRouterDts).not.toMatch(/\b_RouteFileInfoMap\b/)
+  })
+
+  test('vue-router augmentation resolves its type references', async () => {
+    const pluginDts = readFileSync(resolve(buildDir, 'types/i18n-plugin.d.ts'), 'utf-8')
+
+    // Names used inside the `declare module 'vue-router'` block resolve against the file
+    // scope, not the augmented module; without these imports `skipLibCheck` silently turns
+    // the augmentation types into `any`, disabling route narrowing entirely (#3962)
+    for (const name of pluginDts.matchAll(/\b(TypesConfig|RouteMapGeneric|RouteLocation\w*(?:Generic|TypedList))\b/g)) {
+      expect(pluginDts).toMatch(new RegExp(`import type \\{[^}]*\\b${name[1]}\\b[^}]*\\} from 'vue-router'`, 's'))
+    }
+    // removed in vue-router v5
+    expect(pluginDts).not.toContain('_LiteralUnion')
+
+    // narrowing itself is asserted by the `typed_routes` fixture, part of `test:types`
   })
 })

specs/experimental/typed_pages.spec.ts

@@ -0,0 +1,3 @@
+<template>
+  <div>slug</div>
+</template>

specs/fixtures/typed_routes/app/pages/[slug].vue

@@ -0,0 +1,3 @@
+<template>
+  <div>about</div>
+</template>

specs/fixtures/typed_routes/app/pages/about.vue

@@ -0,0 +1,11 @@
+<template>
+  <div>
+    index
+    <NuxtLinkLocale :to="{ name: 'about' }">about</NuxtLinkLocale>
+    <NuxtLinkLocale :to="{ name: 'slug', params: { slug: 'ok' } }">slug</NuxtLinkLocale>
+    <NuxtLinkLocale :to="{ path: '/anything' }" locale="nl">path</NuxtLinkLocale>
+    <NuxtLinkLocale to="about">name string</NuxtLinkLocale>
+    <!-- @vue-expect-error invalid route name -->
+    <NuxtLinkLocale :to="{ name: 'nope' }">invalid</NuxtLinkLocale>
+  </div>
+</template>

specs/fixtures/typed_routes/app/pages/index.vue

@@ -0,0 +1,84 @@
+/**
+ * Type-level assertions for route narrowing with `experimental.typedPages` (#3962).
+ *
+ * Never executed, only checked by this fixture's `test:types` script — an unused
+ * `@ts-expect-error` directive fails the check. The `not.toBeAny()` assertions guard
+ * against the vue-router augmentation silently resolving to `any` when it references
+ * types without importing them (`skipLibCheck` swallows the resolution errors).
+ */
+import { describe, expectTypeOf, it } from 'vitest'
+import { useLocalePath, useLocaleRoute } from '#imports'
+import { useRoute, useRouter } from 'vue-router'
+import type { RouteLocationNamedI18n, RouteMapI18n } from 'vue-router'
+
+describe('vue-router augmentation', () => {
+  it('resolves generated route maps', () => {
+    expectTypeOf<RouteMapI18n>().not.toBeAny()
+    expectTypeOf<keyof RouteMapI18n>().toEqualTypeOf<'index' | 'about' | 'slug'>()
+    expectTypeOf<RouteLocationNamedI18n>().not.toBeAny()
+  })
+
+  it('holds only localized names in vue-router route map', () => {
+    const router = useRouter()
+    router.push({ name: 'slug___en', params: { slug: 'ok' } })
+    // @ts-expect-error base name must not leak into vue-router's RouteMap
+    router.push({ name: 'slug' })
+    // @ts-expect-error invalid route name
+    router.push({ name: 'nope' })
+  })
+})
+
+describe('useLocalePath', () => {
+  const localePath = useLocalePath()
+
+  it('narrows route name strings', () => {
+    localePath('about')
+    localePath('about', 'nl')
+    // @ts-expect-error invalid route name
+    localePath('nope')
+  })
+
+  it('narrows name and params of route objects', () => {
+    localePath({ name: 'about' })
+    localePath({ name: 'slug', params: { slug: 'ok' } })
+    localePath({ name: 'about', query: { q: '1' }, hash: '#x' })
+    // @ts-expect-error invalid route name
+    localePath({ name: 'nope' })
+    // @ts-expect-error wrong param type
+    localePath({ name: 'slug', params: { slug: false } })
+  })
+
+  it('accepts plain string path objects and resolved routes', () => {
+    localePath({ path: '/anything', query: { q: '1' } })
+    localePath(useRoute())
+  })
+})
+
+describe('useLocaleRoute', () => {
+  const localeRoute = useLocaleRoute()
+
+  it('narrows name and params of route objects', () => {
+    // @ts-expect-error invalid route name
+    localeRoute({ name: 'nope' })
+    // @ts-expect-error wrong param type
+    localeRoute({ name: 'slug', params: { slug: false } })
+  })
+
+  it('narrows the resolved route to the given name', () => {
+    const resolved = localeRoute({ name: 'slug', params: { slug: 'ok' } })
+    expectTypeOf(resolved).not.toBeAny()
+    expectTypeOf(resolved!.name).toEqualTypeOf<'slug'>()
+    expectTypeOf(resolved!.params).toEqualTypeOf<{ slug: string }>()
+  })
+})
+
+describe('`NuxtLinkLocale` `to` prop', () => {
+  it('narrows name and params of route objects', () => {
+    expectTypeOf<{ name: 'slug'; params: { slug: 'ok' } }>().toExtend<RouteLocationNamedI18n>()
+    expectTypeOf<{ path: '/anything' }>().toExtend<RouteLocationNamedI18n>()
+    expectTypeOf<'about'>().toExtend<RouteLocationNamedI18n>()
+    expectTypeOf<{ name: 'nope' }>().not.toExtend<RouteLocationNamedI18n>()
+    expectTypeOf<{ name: 'slug'; params: { slug: boolean } }>().not.toExtend<RouteLocationNamedI18n>()
+    expectTypeOf<'nope'>().not.toExtend<RouteLocationNamedI18n>()
+  })
+})

specs/fixtures/typed_routes/app/type-narrowing.ts

@@ -0,0 +1,14 @@
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/i18n'],
+
+  experimental: {
+    typedPages: true,
+  },
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en', 'nl'],
+    strategy: 'prefix_except_default',
+    detectBrowserLanguage: false,
+  },
+})

specs/fixtures/typed_routes/nuxt.config.ts

@@ -0,0 +1,17 @@
+{
+  "name": "fixture-typed-routes",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "nuxi build",
+    "dev": "nuxi dev",
+    "generate": "nuxi generate",
+    "preview": "nuxi preview",
+    "test:types": "nuxi prepare && vue-tsc -b --noEmit"
+  },
+  "devDependencies": {
+    "@nuxtjs/i18n": "latest",
+    "nuxt": "latest",
+    "vue-tsc": "^3.1.9"
+  }
+}