refactor: use object-syntax/named routes (#1041)

.gitignore

···
 
 # generated files
 shared/types/lexicons
+
+# output
+.vercel

app/app.vue

···
       return
     }
 
-    router.push('/search')
+    router.push({ name: 'search' })
   },
   { dedupe: true },
 )

app/components/AppFooter.vue

···
         </div>
         <!-- Desktop: Show all links. Mobile: Links are in MobileMenu -->
         <div class="hidden sm:flex items-center gap-6">
-          <NuxtLink to="/about" class="link-subtle font-mono text-xs flex items-center">
+          <NuxtLink :to="{ name: 'about' }" class="link-subtle font-mono text-xs flex items-center">
             {{ $t('footer.about') }}
           </NuxtLink>
           <NuxtLink
-            to="/privacy"
+            :to="{ name: 'privacy' }"
             class="link-subtle font-mono text-xs min-h-11 flex items-center gap-1 lowercase"
           >
             {{ $t('privacy_policy.title') }}

app/components/AppHeader.vue

···
   e => isKeyWithoutModifiers(e, ',') && !isEditableElement(e.target),
   e => {
     e.preventDefault()
-    navigateTo('/settings')
+    navigateTo({ name: 'settings' })
   },
   { dedupe: true },
 )
···
     !e.defaultPrevented,
   e => {
     e.preventDefault()
-    navigateTo('/compare')
+    navigateTo({ name: 'compare' })
   },
   { dedupe: true },
 )
···
       <!-- Desktop: Logo (navigates home) -->
       <div v-if="showLogo" class="hidden sm:flex flex-shrink-0 items-center">
         <NuxtLink
-          to="/"
+          :to="{ name: 'index' }"
           :aria-label="$t('header.home')"
           dir="ltr"
           class="inline-flex items-center gap-1 header-logo font-mono text-lg font-medium text-fg hover:text-fg/90 transition-colors duration-200 rounded"
···
       <div class="flex-shrink-0 flex items-center gap-0.5 sm:gap-2">
         <!-- Desktop: Compare link -->
         <NuxtLink
-          to="/compare"
+          :to="{ name: 'compare' }"
           class="hidden sm:inline-flex link-subtle font-mono text-sm items-center gap-2 px-2 py-1.5 hover:bg-bg-subtle focus-visible:outline-accent/70 rounded"
           aria-keyshortcuts="c"
         >
···
 
         <!-- Desktop: Settings link -->
         <NuxtLink
-          to="/settings"
+          :to="{ name: 'settings' }"
           class="hidden sm:inline-flex link-subtle font-mono text-sm items-center gap-2 px-2 py-1.5 hover:bg-bg-subtle focus-visible:outline-accent/70 rounded"
           aria-keyshortcuts=","
         >

app/components/Code/DirectoryListing.vue

···
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
+import type { RouteLocationRaw } from 'vue-router'
 import { getFileIcon } from '~/utils/file-icons'
 import { formatBytes } from '~/utils/formatters'
 
···
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
+  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
+  basePath: string[]
 }>()
 
 // Get the current directory's contents
···
   if (parts.length <= 1) return ''
   return parts.slice(0, -1).join('/')
 })
+
+// Build route object for a path
+function getCodeRoute(nodePath?: string): RouteLocationRaw {
+  if (!nodePath) {
+    return { name: 'code', params: { path: props.basePath as [string, ...string[]] } }
+  }
+  const pathSegments = [...props.basePath, ...nodePath.split('/')]
+  return {
+    name: 'code',
+    params: { path: pathSegments as [string, ...string[]] },
+  }
+}
 </script>
 
 <template>
···
         >
           <td class="py-2 px-4">
             <NuxtLink
-              :to="parentPath ? `${baseUrl}/${parentPath}` : baseUrl"
+              :to="getCodeRoute(parentPath || undefined)"
               class="flex items-center gap-2 font-mono text-sm text-fg-muted hover:text-fg transition-colors"
             >
               <span class="i-carbon:folder w-4 h-4 text-yellow-600" />
···
         >
           <td class="py-2 px-4">
             <NuxtLink
-              :to="`${baseUrl}/${node.path}`"
+              :to="getCodeRoute(node.path)"
               class="flex items-center gap-2 font-mono text-sm hover:text-fg transition-colors"
               :class="node.type === 'directory' ? 'text-fg' : 'text-fg-muted'"
             >

app/components/Code/FileTree.vue

···
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
+import type { RouteLocationRaw } from 'vue-router'
 import { getFileIcon } from '~/utils/file-icons'
 
 const props = defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
+  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
+  basePath: string[]
   depth?: number
 }>()
 
···
   if (props.currentPath === node.path) return true
   if (props.currentPath.startsWith(node.path + '/')) return true
   return false
+}
+
+// Build route object for a file path
+function getFileRoute(nodePath: string): RouteLocationRaw {
+  const pathSegments = [...props.basePath, ...nodePath.split('/')]
+  return {
+    name: 'code',
+    params: { path: pathSegments as [string, ...string[]] },
+  }
 }
 
 const { toggleDir, isExpanded, autoExpandAncestors } = useFileTreeState(props.baseUrl)
···
           :tree="node.children"
           :current-path="currentPath"
           :base-url="baseUrl"
+          :base-path="basePath"
           :depth="depth + 1"
         />
       </template>
···
       <!-- File -->
       <template v-else>
         <NuxtLink
-          :to="`${baseUrl}/${node.path}`"
+          :to="getFileRoute(node.path)"
           class="flex items-center gap-1.5 py-1.5 px-3 font-mono text-sm transition-colors hover:bg-bg-muted"
           :class="currentPath === node.path ? 'bg-bg-muted text-fg' : 'text-fg-muted'"
           :style="{ paddingLeft: `${depth * 12 + 32}px` }"

app/components/Code/MobileTreeDrawer.vue

···
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
+  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
+  basePath: string[]
 }>()
 
 const isOpen = shallowRef(false)
···
           <span class="i-carbon:close w-5 h-5" />
         </button>
       </div>
-      <CodeFileTree :tree="tree" :current-path="currentPath" :base-url="baseUrl" />
+      <CodeFileTree
+        :tree="tree"
+        :current-path="currentPath"
+        :base-url="baseUrl"
+        :base-path="basePath"
+      />
     </aside>
   </Transition>
 </template>

app/components/Compare/ComparisonGrid.vue

···
         >
           <span class="inline-flex items-center gap-1.5 truncate">
             <NuxtLink
-              :to="`/package/${col.header}`"
+              :to="packageRoute(col.header)"
               class="link-subtle font-mono text-sm font-medium text-fg truncate"
               :title="col.header"
             >

app/components/Compare/PackageSelector.vue

···
         </template>
         <NuxtLink
           v-else
-          :to="`/package/${pkg}`"
+          :to="packageRoute(pkg)"
           class="font-mono text-sm text-fg hover:text-accent transition-colors"
         >
           {{ pkg }}

app/components/DependencyPathPopup.vue

···
           >
             <span v-if="idx > 0" class="text-fg-subtle me-1">└─</span>
             <NuxtLink
-              :to="{
-                name: 'package',
-                params: {
-                  package: [
-                    ...parsePackageString(pathItem).name.split('/'),
-                    'v',
-                    parsePackageString(pathItem).version,
-                  ],
-                },
-              }"
+              :to="
+                packageRoute(
+                  parsePackageString(pathItem).name,
+                  parsePackageString(pathItem).version,
+                )
+              "
               class="hover:underline"
               :class="idx === path.length - 1 ? 'text-fg font-medium' : 'text-fg-muted'"
               @click="closePopup"

app/components/Header/MobileMenu.client.vue

···
               <!-- Main navigation -->
               <div class="px-2 py-2">
                 <NuxtLink
-                  to="/about"
+                  :to="{ name: 'about' }"
                   class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                   @click="closeMenu"
                 >
···
                 </NuxtLink>
 
                 <NuxtLink
-                  to="/privacy"
+                  :to="{ name: 'privacy' }"
                   class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                   @click="closeMenu"
                 >
···
                 </NuxtLink>
 
                 <NuxtLink
-                  to="/compare"
+                  :to="{ name: 'compare' }"
                   class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                   @click="closeMenu"
                 >
···
                 </NuxtLink>
 
                 <NuxtLink
-                  to="/settings"
+                  :to="{ name: 'settings' }"
                   class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                   @click="closeMenu"
                 >
···
                 <!-- Connected user links -->
                 <template v-if="isConnected && npmUser">
                   <NuxtLink
-                    :to="`/~${npmUser}`"
+                    :to="{ name: '~username', params: { username: npmUser } }"
                     class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                     @click="closeMenu"
                   >
···
                   </NuxtLink>
 
                   <NuxtLink
-                    :to="`/~${npmUser}/orgs`"
+                    :to="{ name: '~username-orgs', params: { username: npmUser } }"
                     class="flex items-center gap-3 px-3 py-3 rounded-md font-mono text-sm text-fg hover:bg-bg-subtle transition-colors duration-200"
                     @click="closeMenu"
                   >

app/components/Header/OrgsDropdown.vue

···
     @keydown="handleKeydown"
   >
     <NuxtLink
-      :to="`/~${username}/orgs`"
+      :to="{ name: '~username-orgs', params: { username } }"
       class="link-subtle font-mono text-sm inline-flex items-center gap-1"
     >
       {{ $t('header.orgs') }}
···
           <ul v-else-if="orgs.length > 0" class="py-1 max-h-80 overflow-y-auto">
             <li v-for="org in orgs" :key="org">
               <NuxtLink
-                :to="`/@${org}`"
+                :to="{ name: 'org', params: { org } }"
                 class="block px-3 py-2 font-mono text-sm text-fg hover:bg-bg-subtle transition-colors"
               >
                 @{{ org }}
···
 
           <div class="px-3 py-2 border-t border-border">
             <NuxtLink
-              :to="`/~${username}/orgs`"
+              :to="{ name: '~username-orgs', params: { username } }"
               class="link-subtle font-mono text-xs inline-flex items-center gap-1"
             >
               {{ $t('header.orgs_dropdown.view_all') }}

app/components/Header/PackagesDropdown.vue

···
     @keydown="handleKeydown"
   >
     <NuxtLink
-      :to="`/~${username}`"
+      :to="{ name: '~username', params: { username } }"
       class="link-subtle font-mono text-sm inline-flex items-center gap-1"
     >
       {{ $t('header.packages') }}
···
           <ul v-else-if="packages.length > 0" class="py-1 max-h-80 overflow-y-auto">
             <li v-for="pkg in packages" :key="pkg">
               <NuxtLink
-                :to="`/package/${pkg}`"
+                :to="packageRoute(pkg)"
                 class="block px-3 py-2 font-mono text-sm text-fg hover:bg-bg-subtle transition-colors truncate"
               >
                 {{ pkg }}
···
 
           <div class="px-3 py-2 border-t border-border">
             <NuxtLink
-              :to="`/~${username}`"
+              :to="{ name: '~username', params: { username } }"
               class="link-subtle font-mono text-xs inline-flex items-center gap-1"
             >
               {{ $t('header.packages_dropdown.view_all') }}

app/components/Package/Card.vue

···
         class="font-mono text-sm sm:text-base font-medium text-fg group-hover:text-fg transition-colors duration-200 min-w-0 break-all"
       >
         <NuxtLink
-          :to="{ name: 'package', params: { package: result.package.name.split('/') } }"
+          :to="packageRoute(result.package.name)"
           :prefetch-on="prefetch ? 'visibility' : 'interaction'"
           class="decoration-none scroll-mt-48 scroll-mb-6 after:content-[''] after:absolute after:inset-0"
           :data-result-index="index"

app/components/Package/ClaimPackageModal.vue

···
 
       <div class="flex gap-3">
         <NuxtLink
-          :to="`/package/${packageName}`"
+          :to="packageRoute(packageName)"
           class="flex-1 px-4 py-2 font-mono text-sm text-center text-bg bg-fg rounded-md transition-colors duration-200 hover:bg-fg/90 focus-visible:outline-accent/70"
           @click="close"
         >
···
               <span v-else class="w-4 h-4 shrink-0" />
               <div class="min-w-0">
                 <NuxtLink
-                  :to="`/package/${pkg.name}`"
+                  :to="packageRoute(pkg.name)"
                   class="font-mono text-sm text-fg hover:underline focus-visible:outline-accent/70 rounded"
                   target="_blank"
                 >

app/components/Package/Dependencies.vue

···
           class="flex items-center justify-between py-1 text-sm gap-2"
         >
           <NuxtLink
-            :to="{ name: 'package', params: { package: dep.split('/') } }"
+            :to="packageRoute(dep)"
             class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate min-w-0 flex-1"
           >
             {{ dep }}
···
             </span>
             <NuxtLink
               v-if="getVulnerableDepInfo(dep)"
-              :to="{
-                name: 'package',
-                params: { package: [...dep.split('/'), 'v', getVulnerableDepInfo(dep)!.version] },
-              }"
+              :to="packageRoute(dep, getVulnerableDepInfo(dep)!.version)"
               class="shrink-0"
               :class="SEVERITY_TEXT_COLORS[getHighestSeverity(getVulnerableDepInfo(dep)!.counts)]"
               :title="`${getVulnerableDepInfo(dep)!.counts.total} vulnerabilities`"
···
             </NuxtLink>
             <NuxtLink
               v-if="getDeprecatedDepInfo(dep)"
-              :to="{
-                name: 'package',
-                params: { package: [...dep.split('/'), 'v', getDeprecatedDepInfo(dep)!.version] },
-              }"
+              :to="packageRoute(dep, getDeprecatedDepInfo(dep)!.version)"
               class="shrink-0 text-purple-500"
               :title="getDeprecatedDepInfo(dep)!.message"
             >
···
               <span class="sr-only">{{ $t('package.deprecated.label') }}</span>
             </NuxtLink>
             <NuxtLink
-              :to="{
-                name: 'package',
-                params: { package: [...dep.split('/'), 'v', version] },
-              }"
+              :to="packageRoute(dep, version)"
               class="font-mono text-xs text-end truncate"
               :class="getVersionClass(outdatedDeps[dep])"
               :title="outdatedDeps[dep] ? getOutdatedTooltip(outdatedDeps[dep], $t) : version"
···
         >
           <div class="flex items-center gap-1 min-w-0 flex-1">
             <NuxtLink
-              :to="{
-                name: 'package',
-                params: { package: peer.name.split('/') },
-              }"
+              :to="packageRoute(peer.name)"
               class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate"
             >
               {{ peer.name }}
···
             </span>
           </div>
           <NuxtLink
-            :to="{
-              name: 'package',
-              params: { package: [...peer.name.split('/'), 'v', peer.version] },
-            }"
+            :to="packageRoute(peer.name, peer.version)"
             class="font-mono text-xs text-fg-subtle max-w-[40%] truncate"
             :title="peer.version"
           >
···
           class="flex items-center justify-between py-1 text-sm gap-2"
         >
           <NuxtLink
-            :to="{ name: 'package', params: { package: dep.split('/') } }"
+            :to="packageRoute(dep)"
             class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate min-w-0 flex-1"
           >
             {{ dep }}
           </NuxtLink>
           <NuxtLink
-            :to="{
-              name: 'package',
-              params: { package: [...dep.split('/'), 'v', version] },
-            }"
+            :to="packageRoute(dep, version)"
             class="font-mono text-xs text-fg-subtle max-w-[40%] text-end truncate"
             :title="version"
           >

app/components/Package/DeprecatedTree.vue

···
               <DependencyPathPopup v-if="pkg.path && pkg.path.length > 1" :path="pkg.path" />
 
               <NuxtLink
-                :to="{
-                  name: 'package',
-                  params: { package: [...pkg.name.split('/'), 'v', pkg.version] },
-                }"
+                :to="packageRoute(pkg.name, pkg.version)"
                 class="font-mono text-sm font-medium hover:underline truncate py-4"
                 :class="getDepthStyle(pkg.depth).text"
               >

app/components/Package/InstallScripts.vue

···
           class="flex items-center justify-between py-0.5 text-sm gap-2"
         >
           <NuxtLink
-            :to="{ name: 'package', params: { package: dep.split('/') } }"
+            :to="packageRoute(dep)"
             class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate min-w-0"
           >
             {{ dep }}

app/components/Package/TableRow.vue

···
   return props.columns.find(c => c.id === id)?.visible ?? false
 }
 
-const packageUrl = computed(() => `/package/${pkg.value.name}`)
+const packageUrl = computed(() => packageRoute(pkg.value.name))
 
 const allMaintainersText = computed(() => {
   if (!pkg.value.maintainers?.length) return ''
···
           :key="maintainer.username || maintainer.email"
         >
           <NuxtLink
-            :to="`/~${maintainer.username || maintainer.name}`"
+            :to="{
+              name: '~username',
+              params: { username: maintainer.username || maintainer.name || '' },
+            }"
             class="hover:text-accent-fallback transition-colors duration-200"
             @click.stop
             >{{ maintainer.username || maintainer.name || maintainer.email }}</NuxtLink

app/components/Package/Versions.vue

···
 
 // Build route object for package version link
 function versionRoute(version: string): RouteLocationRaw {
-  return {
-    name: 'package',
-    params: { package: [...props.packageName.split('/'), 'v', version] },
-  }
+  return packageRoute(props.packageName, version)
 }
 
 // Version to tags lookup (supports multiple tags per version)

app/components/Package/VulnerabilityTree.vue

···
                 <DependencyPathPopup v-if="pkg.path && pkg.path.length > 1" :path="pkg.path" />
 
                 <NuxtLink
-                  :to="{
-                    name: 'package',
-                    params: { package: [...pkg.name.split('/'), 'v', pkg.version] },
-                  }"
+                  :to="packageRoute(pkg.name, pkg.version)"
                   class="font-mono text-sm font-medium hover:underline truncate shrink min-w-0"
                   :class="getDepthStyle(pkg.depth).text"
                 >

app/components/Terminal/Install.vue

···
               ></code
             >
             <NuxtLink
-              :to="`/package/${typesPackageName}`"
+              :to="packageRoute(typesPackageName!)"
               class="text-fg-subtle hover:text-fg-muted text-xs transition-colors focus-visible:outline-accent/70 rounded select-none"
               :title="$t('package.get_started.view_types', { package: typesPackageName })"
             >
···
               :text="$t('package.create.view', { packageName: createPackageInfo.packageName })"
             >
               <NuxtLink
-                :to="`/package/${createPackageInfo.packageName}`"
+                :to="packageRoute(createPackageInfo.packageName)"
                 class="inline-flex items-center justify-center min-w-6 min-h-6 -m-1 p-1 text-fg-muted hover:text-fg text-xs transition-colors focus-visible:outline-2 focus-visible:outline-accent/70 rounded"
               >
                 <span class="i-carbon:information w-3 h-3" aria-hidden="true" />

app/components/VersionSelector.vue

···
         <!-- Link to package page for full version list -->
         <div class="border-t border-border mt-1 pt-1 px-3 py-2">
           <NuxtLink
-            :to="`/package/${packageName}`"
+            :to="packageRoute(packageName)"
             class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
             @click="isOpen = false"
           >

app/composables/usePackageRoute.ts

···
 /**
  * Parse package name and optional version from the route URL.
  *
- * Supported patterns:
- *   /nuxt → packageName: "nuxt", requestedVersion: null
- *   /nuxt/v/4.2.0 → packageName: "nuxt", requestedVersion: "4.2.0"
- *   /@nuxt/kit → packageName: "@nuxt/kit", requestedVersion: null
- *   /@nuxt/kit/v/1.0.0 → packageName: "@nuxt/kit", requestedVersion: "1.0.0"
- *   /axios@1.13.3 → packageName: "axios", requestedVersion: "1.13.3"
- *   /@nuxt/kit@1.0.0 → packageName: "@nuxt/kit", requestedVersion: "1.0.0"
+ * Routes use structured params:
+ *   /package/nuxt → org: undefined, name: "nuxt"
+ *   /package/@nuxt/kit → org: "@nuxt", name: "kit"
+ *   /package/nuxt/v/4.2.0 → org: undefined, name: "nuxt", version: "4.2.0"
+ *   /package/@nuxt/kit/v/1.0.0 → org: "@nuxt", name: "kit", version: "1.0.0"
  */
 export function usePackageRoute() {
-  const route = useRoute('package')
-
-  const parsedRoute = computed(() => {
-    const segments = route.params.package?.filter(Boolean) || []
+  const route = useRoute<'package'>('package')
 
-    // Find the /v/ separator for version
-    const vIndex = segments.indexOf('v')
-    if (vIndex !== -1 && vIndex < segments.length - 1) {
-      return {
-        packageName: segments.slice(0, vIndex).join('/'),
-        requestedVersion: segments.slice(vIndex + 1).join('/'),
-      }
-    }
-
-    // Parse @ versioned package
-    const fullPath = segments.join('/')
-    const versionMatch = fullPath.match(/^(@[^/]+\/[^/]+|[^/]+)@([^/]+)$/)
-    if (versionMatch) {
-      const [, packageName, requestedVersion] = versionMatch as [string, string, string]
-      return {
-        packageName,
-        requestedVersion,
-      }
-    }
-
-    return {
-      packageName: fullPath,
-      requestedVersion: null as string | null,
-    }
+  const packageName = computed(() => {
+    const { org, name } = route.params
+    return org ? `${org}/${name}` : name
   })
 
-  const packageName = computed(() => parsedRoute.value.packageName)
-  const requestedVersion = computed(() => parsedRoute.value.requestedVersion)
-
-  // Extract org name from scoped package (e.g., "@nuxt/kit" -> "nuxt")
+  const requestedVersion = computed(() => ('version' in route.params ? route.params.version : null))
   const orgName = computed(() => {
-    const name = packageName.value
-    if (!name.startsWith('@')) return null
-    const match = name.match(/^@([^/]+)\//)
-    return match ? match[1] : null
+    const org = route.params.org
+    return org ? org.replace(/^@/, '') : null
   })
 
   return {

app/middleware/canonical-redirects.global.ts

···
-/**
- * Redirect legacy URLs to canonical paths (client-side only)
- *
- * - /package/code/* → /package-code/*
- * - /code/* → /package-code/*
- * - /package/docs/* → /package-docs/*
- * - /docs/* → /package-docs/*
- * - /org/* → /@*
- * - /* → /package/* (Unless it's an existing page)
- */
-export default defineNuxtRouteMiddleware(to => {
-  // Only redirect on client-side to avoid breaking crawlers mid-transition
-  if (import.meta.server) return
-
-  const path = to.path
-
-  // /package/code/* → /package-code/*
-  if (path.startsWith('/package/code/')) {
-    return navigateTo(path.replace('/package/code/', '/package-code/'), { replace: true })
-  }
-  // /code/* → /package-code/*
-  if (path.startsWith('/code/')) {
-    return navigateTo(path.replace('/code/', '/package-code/'), { replace: true })
-  }
-
-  // /package/docs/* → /package-docs/*
-  if (path.startsWith('/package/docs/')) {
-    return navigateTo(path.replace('/package/docs/', '/package-docs/'), { replace: true })
-  }
-  // /docs/* → /package-docs/*
-  if (path.startsWith('/docs/')) {
-    return navigateTo(path.replace('/docs/', '/package-docs/'), { replace: true })
-  }
-
-  // /org/* → /@*
-  if (path.startsWith('/org/')) {
-    return navigateTo(path.replace('/org/', '/@'), { replace: true })
-  }
-
-  // Keep this one last as it will catch everything
-  // /* → /package/* (Unless it's an existing page)
-  if (path.startsWith('/') && !path.startsWith('/package/')) {
-    const router = useRouter()
-    const resolved = router.resolve(path)
-    if (resolved?.matched?.length === 1 && resolved.matched[0]?.path === '/:package(.*)*') {
-      return navigateTo(`/package${path}`, { replace: true })
-    }
-  }
-})

app/pages/@[org].vue app/pages/org/[org].vue

···
 
 definePageMeta({
   name: 'org',
-  alias: ['/org/:org()'],
 })
 
 const route = useRoute('org')
···
       <p class="text-fg-muted mb-4">
         {{ error?.message ?? $t('org.page.failed_to_load') }}
       </p>
-      <NuxtLink to="/" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
+      <NuxtLink :to="{ name: 'index' }" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
     </div>
 
     <!-- Empty state -->

app/pages/index.vue

···
         <ul class="flex flex-wrap items-center justify-center gap-x-6 gap-y-3 list-none m-0 p-0">
           <li v-for="framework in SHOWCASED_FRAMEWORKS" :key="framework.name">
             <NuxtLink
-              :to="{ name: 'package', params: { package: [framework.package] } }"
+              :to="packageRoute(framework.package)"
               class="link-subtle font-mono text-sm inline-flex items-center gap-2 group"
             >
               <span

app/pages/package-code/[...path].vue

···
   return path ? `${base}/${path}` : base
 }
 
+// Base path segments for route objects (e.g., ['nuxt', 'v', '4.2.0'] or ['@nuxt', 'kit', 'v', '1.0.0'])
+const basePath = computed(() => {
+  const segments = packageName.value.split('/')
+  return [...segments, 'v', version.value ?? '']
+})
+
 // Extract org name from scoped package
 const orgName = computed(() => {
   const name = packageName.value
···
   return match ? match[1] : null
 })
 
-// Build route object for package link (with optional version)
-function packageRoute(ver?: string | null) {
-  const segments = packageName.value.split('/')
-  if (ver) {
-    segments.push('v', ver)
-  }
-  return { name: 'package' as const, params: { package: segments } }
-}
-
 // Line number click handler - update URL hash without scrolling
 function handleLineClick(lineNum: number, event: MouseEvent) {
   let newHash: string
···
         <!-- Package info and navigation -->
         <div class="flex items-center gap-2 mb-3 flex-wrap min-w-0">
           <NuxtLink
-            :to="packageRoute(version)"
+            :to="packageRoute(packageName, version)"
             class="font-mono text-lg font-medium hover:text-fg transition-colors min-w-0 truncate max-w-[60vw] sm:max-w-none"
             :title="packageName"
           >
···
     <!-- Error: no version -->
     <div v-if="!version" class="container py-20 text-center">
       <p class="text-fg-muted mb-4">{{ $t('code.version_required') }}</p>
-      <NuxtLink :to="packageRoute()" class="btn">{{ $t('code.go_to_package') }}</NuxtLink>
+      <NuxtLink :to="packageRoute(packageName)" class="btn">{{
+        $t('code.go_to_package')
+      }}</NuxtLink>
     </div>
 
     <!-- Loading state -->
···
     <!-- Error state -->
     <div v-else-if="treeStatus === 'error'" class="container py-20 text-center" role="alert">
       <p class="text-fg-muted mb-4">{{ $t('code.failed_to_load_tree') }}</p>
-      <NuxtLink :to="packageRoute(version)" class="btn">{{ $t('code.back_to_package') }}</NuxtLink>
+      <NuxtLink :to="packageRoute(packageName, version)" class="btn">{{
+        $t('code.back_to_package')
+      }}</NuxtLink>
     </div>
 
     <!-- Main content: file tree + file viewer -->
···
           :tree="fileTree.tree"
           :current-path="filePath ?? ''"
           :base-url="getCodeUrl()"
+          :base-path="basePath"
         />
       </aside>
 
···
             :tree="fileTree.tree"
             :current-path="filePath ?? ''"
             :base-url="getCodeUrl()"
+            :base-path="basePath"
           />
         </template>
       </div>
···
           :tree="fileTree.tree"
           :current-path="filePath ?? ''"
           :base-url="getCodeUrl()"
+          :base-path="basePath"
         />
       </Teleport>
     </ClientOnly>

app/pages/package-docs/[...path].vue

···
   const version = await fetchLatestVersion(packageName.value)
   if (version) {
     setResponseHeader(useRequestEvent()!, 'Cache-Control', 'no-cache')
+    const pathSegments = [...packageName.value.split('/'), 'v', version]
     app.runWithContext(() =>
-      navigateTo('/package-docs/' + packageName.value + '/v/' + version, { redirectCode: 302 }),
+      navigateTo(
+        { name: 'docs', params: { path: pathSegments as [string, ...string[]] } },
+        { redirectCode: 302 },
+      ),
     )
   }
 }
···
   [requestedVersion, latestVersion, packageName],
   ([version, latest, name]) => {
     if (!version && latest && name) {
-      router.replace(`/package-docs/${name}/v/${latest}`)
+      const pathSegments = [...name.split('/'), 'v', latest]
+      router.replace({ name: 'docs', params: { path: pathSegments as [string, ...string[]] } })
     }
   },
   { immediate: true },
···
           <div class="flex items-center gap-3 min-w-0">
             <NuxtLink
               v-if="packageName"
-              :to="{ name: 'package', params: { package: [packageName] } }"
+              :to="packageRoute(packageName)"
               class="font-mono text-lg sm:text-xl font-semibold text-fg hover:text-fg-muted transition-colors truncate"
             >
               {{ packageName }}
···
             <div class="flex gap-4 mt-4">
               <NuxtLink
                 v-if="packageName"
-                :to="{ name: 'package', params: { package: [packageName] } }"
+                :to="packageRoute(packageName)"
                 class="link-subtle font-mono text-sm"
               >
                 View package

app/pages/package/[...package].vue app/pages/package/[[org]]/[name].vue

···
 import { useAtproto } from '~/composables/atproto/useAtproto'
 import { togglePackageLike } from '~/utils/atproto/likes'
 
-definePageMeta({
-  name: 'package',
-  alias: ['/:package(.*)*'],
-})
-
 defineOgImageComponent('Package', {
   name: () => packageName.value,
   version: () => requestedVersion.value ?? '',
···
 const docsLink = computed(() => {
   if (!resolvedVersion.value) return null
 
-  return `/package-docs/${pkg.value!.name}/v/${resolvedVersion.value}`
+  return {
+    name: 'docs' as const,
+    params: {
+      path: [pkg.value!.name, 'v', resolvedVersion.value] satisfies [string, string, string],
+    },
+  }
 })
 
 const fundingUrl = computed(() => {
···
   e => {
     if (!pkg.value) return
     e.preventDefault()
-    router.push({ path: '/compare', query: { packages: pkg.value.name } })
+    router.push({ name: 'compare', query: { packages: pkg.value.name } })
   },
 )
 </script>
···
 
             <NuxtLink
               v-if="requestedVersion && resolvedVersion !== requestedVersion"
-              :to="`/package/${pkg.name}/v/${resolvedVersion}`"
+              :to="packageRoute(pkg.name, resolvedVersion)"
               :title="$t('package.view_permalink')"
               >{{ resolvedVersion }}</NuxtLink
             >
···
               </kbd>
             </NuxtLink>
             <NuxtLink
-              :to="`/package-code/${pkg.name}/v/${resolvedVersion}`"
+              :to="{ name: 'code', params: { path: [pkg.name, 'v', resolvedVersion] } }"
               class="px-2 py-1.5 font-mono text-xs rounded transition-colors duration-150 border border-transparent text-fg-subtle hover:text-fg hover:bg-bg hover:shadow hover:border-border inline-flex items-center gap-1.5"
               aria-keyshortcuts="."
             >
···
               </kbd>
             </NuxtLink>
             <NuxtLink
-              :to="{ path: '/compare', query: { packages: pkg.name } }"
+              :to="{ name: 'compare', query: { packages: pkg.name } }"
               class="px-2 py-1.5 font-mono text-xs rounded transition-colors duration-150 border border-transparent text-fg-subtle hover:text-fg hover:bg-bg hover:shadow hover:border-border inline-flex items-center gap-1.5"
               aria-keyshortcuts="c"
             >
···
             </li>
             <li v-if="resolvedVersion" class="sm:hidden">
               <NuxtLink
-                :to="`/package-code/${pkg.name}/v/${resolvedVersion}`"
+                :to="{ name: 'code', params: { path: [pkg.name, 'v', resolvedVersion] } }"
                 class="link-subtle font-mono text-sm inline-flex items-center gap-1.5"
               >
                 <span class="i-carbon:code w-4 h-4" aria-hidden="true" />
···
             </li>
             <li class="sm:hidden">
               <NuxtLink
-                :to="{ path: '/compare', query: { packages: pkg.name } }"
+                :to="{ name: 'compare', query: { packages: pkg.name } }"
                 class="link-subtle font-mono text-sm inline-flex items-center gap-1.5"
               >
                 <span class="i-carbon:compare w-4 h-4" aria-hidden="true" />
···
       <p class="text-fg-muted mb-8">
         {{ error?.message ?? $t('package.not_found_message') }}
       </p>
-      <NuxtLink to="/" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
+      <NuxtLink :to="{ name: 'index' }" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
     </div>
   </main>
 </template>

app/pages/package/[[org]]/[name]/index.vue

···
+<script setup lang="ts">
+// stub page to help with paths
+definePageMeta({
+  name: 'package',
+})
+</script>
+
+<template>
+  <div />
+</template>

app/pages/package/[[org]]/[name]/v/[version].vue

···
+<script setup lang="ts">
+// stub page to help with paths
+definePageMeta({
+  name: 'package-version',
+})
+</script>
+
+<template>
+  <div />
+</template>

app/pages/privacy.vue

···
               </template>
               <template #settings>
                 <NuxtLink
-                  to="/settings"
+                  :to="{ name: 'settings' }"
                   class="text-fg-muted hover:text-fg underline decoration-fg-subtle/50 hover:decoration-fg"
                 >
                   {{ $t('privacy_policy.cookies.local_storage.settings') }}
···
             <i18n-t keypath="privacy_policy.authenticated.p2" tag="span" scope="global">
               <template #settings>
                 <NuxtLink
-                  to="/settings"
+                  :to="{ name: 'settings' }"
                   class="text-fg-muted hover:text-fg underline decoration-fg-subtle/50 hover:decoration-fg"
                 >
                   {{ $t('privacy_policy.authenticated.settings') }}

app/pages/search.vue

···
 
 // Navigate to package page
 async function navigateToPackage(packageName: string) {
-  await navigateTo({
-    name: 'package',
-    params: { package: packageName.split('/') },
-  })
+  await navigateTo(packageRoute(packageName))
 }
 
 // Track the input value when user pressed Enter (for navigating when results arrive)

app/pages/~[username]/index.vue

···
       <p class="text-fg-muted mb-4">
         {{ error?.message ?? $t('user.page.failed_to_load') }}
       </p>
-      <NuxtLink to="/" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
+      <NuxtLink :to="{ name: 'index' }" class="btn">{{ $t('common.go_back_home') }}</NuxtLink>
     </div>
 
     <!-- Package list -->

app/pages/~[username]/orgs.vue

···
       <!-- Back link -->
       <nav aria-labelledby="back-to-profile">
         <NuxtLink
-          :to="`/~${username}`"
+          :to="{ name: '~username', params: { username } }"
           id="back-to-profile"
           class="link-subtle font-mono text-sm inline-flex items-center gap-1.5"
         >
···
       <!-- Not own profile state -->
       <div v-else-if="!isOwnProfile" class="py-12 text-center">
         <p class="text-fg-muted">{{ $t('user.orgs_page.own_orgs_only') }}</p>
-        <NuxtLink :to="`/~${npmUser}/orgs`" class="btn mt-4">{{
-          $t('user.orgs_page.view_your_orgs')
-        }}</NuxtLink>
+        <NuxtLink
+          :to="{ name: '~username-orgs', params: { username: npmUser! } }"
+          class="btn mt-4"
+          >{{ $t('user.orgs_page.view_your_orgs') }}</NuxtLink
+        >
       </div>
 
       <!-- Loading state -->
···
         <ul class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
           <li v-for="org in orgs" :key="org.name">
             <NuxtLink
-              :to="`/@${org.name}`"
+              :to="{ name: 'org', params: { org: org.name } }"
               class="block p-5 bg-bg-subtle border border-border rounded-lg hover:border-fg-subtle transition-colors h-full"
             >
               <div class="flex items-start gap-4 mb-4">

app/utils/router.ts

···
+export function packageRoute(packageName: string, version?: string | null) {
+  const [org, name] = packageName.startsWith('@') ? packageName.split('/') : [null, packageName]
+
+  if (version) {
+    return {
+      name: 'package-version' as const,
+      params: {
+        org,
+        name,
+        version,
+      },
+    }
+  }
+
+  return {
+    name: 'package' as const,
+    params: {
+      org,
+      name,
+    },
+  }
+}

modules/isr-fallback.ts

···
-import { readFileSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { defineNuxtModule } from 'nuxt/kit'
 import { provider } from 'std-env'
···
     nuxt.hook('nitro:init', nitro => {
       nitro.hooks.hook('compiled', () => {
         const spaTemplate = readFileSync(nitro.options.output.publicDir + '/200.html', 'utf-8')
-        for (const path of ['package', '']) {
+        for (const path of [
+          'package',
+          'package/[name]',
+          'package/[name]/v',
+          'package/[name]/v/[version]',
+          'package/[org]',
+          'package/[org]/[name]',
+          'package/[org]/[name]/v',
+          'package/[org]/[name]/v/[version]',
+          '',
+        ]) {
           const outputPath = resolve(
             nitro.options.output.serverDir,
             '..',
             path,
             'spa.prerender-fallback.html',
           )
+          mkdirSync(resolve(nitro.options.output.serverDir, '..', path), { recursive: true })
           writeFileSync(outputPath, spaTemplate)
         }
       })

nuxt.config.ts

···
   },
 
   routeRules: {
-    '/': { prerender: true },
-    '/opensearch.xml': { isr: true },
-    '/**': { isr: getISRConfig(60, true) },
-    '/__og-image__/**': { isr: getISRConfig(60) },
+    // API routes
     '/api/**': { isr: 60 },
-    '/200.html': { prerender: true },
-    '/package/**': { isr: getISRConfig(60, true) },
+    '/api/registry/docs/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
+    '/api/registry/file/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
+    '/api/registry/provenance/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
+    '/api/registry/files/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     '/:pkg/.well-known/skills/**': { isr: 3600 },
     '/:scope/:pkg/.well-known/skills/**': { isr: 3600 },
+    '/__og-image__/**': { isr: getISRConfig(60) },
+    '/_avatar/**': { isr: 3600, proxy: 'https://www.gravatar.com/avatar/**' },
+    '/opensearch.xml': { isr: true },
+    '/oauth-client-metadata.json': { prerender: true },
     // never cache
-    '/search': { isr: false, cache: false },
     '/api/auth/**': { isr: false, cache: false },
     '/api/social/**': { isr: false, cache: false },
     '/api/opensearch/suggestions': {
···
         allowQuery: ['q'],
       },
     },
+    // pages
+    '/package/:name': { isr: getISRConfig(60, true) },
+    '/package/:name/v/:version': { isr: getISRConfig(60, true) },
+    '/package/:org/:name': { isr: getISRConfig(60, true) },
+    '/package/:org/:name/v/:version': { isr: getISRConfig(60, true) },
     // infinite cache (versioned - doesn't change)
     '/package-code/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/package-docs/:pkg/v/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/package-docs/:scope/:pkg/v/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/api/registry/docs/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/api/registry/file/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/api/registry/provenance/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/api/registry/files/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
-    '/_avatar/**': {
-      isr: 3600,
-      proxy: {
-        to: 'https://www.gravatar.com/avatar/**',
-      },
-    },
+    '/package-docs/:name/v/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
+    '/package-docs/:org/:name/v/**': { isr: true, cache: { maxAge: 365 * 24 * 60 * 60 } },
     // static pages
+    '/': { prerender: true },
+    '/200.html': { prerender: true },
     '/about': { prerender: true },
+    '/privacy': { prerender: true },
+    '/search': { isr: false, cache: false }, // never cache
     '/settings': { prerender: true },
-    '/oauth-client-metadata.json': { prerender: true },
     // proxy for insights
     '/_v/script.js': { proxy: 'https://npmx.dev/_vercel/insights/script.js' },
     '/_v/view': { proxy: 'https://npmx.dev/_vercel/insights/view' },

server/middleware/canonical-redirects.global.ts

···
+/**
+ * Redirect legacy/shorthand URLs to canonical paths.
+ *
+ * Handled here:
+ * - /@org/pkg or /pkg           → /package/@org/pkg or /package/pkg
+ * - /@org/pkg/v/ver or /pkg@ver → /package/@org/pkg/v/ver or /package/pkg/v/ver
+ * - /@org                       → /org/org
+ *
+ * Handled via route aliases (not here):
+ * - /package/code/* → /package-code/*
+ * - /code/*         → /package-code/*
+ * - /package/docs/* → /package-docs/*
+ * - /docs/*         → /package-docs/*
+ */
+const pages = [
+  '/200.html',
+  '/about',
+  '/compare',
+  '/org',
+  '/package',
+  '/package-code',
+  '/package-docs',
+  '/privacy',
+  '/search',
+  '/settings',
+]
+
+const cacheControl = 's-maxage=3600, stale-while-revalidate=36000'
+
+export default defineEventHandler(async event => {
+  const routeRules = getRouteRules(event)
+  if (Object.keys(routeRules).length > 1) {
+    return
+  }
+
+  const [path = '/', query] = event.path.split('?')
+
+  // username
+  if (path.startsWith('/~') || path.startsWith('/_')) {
+    return
+  }
+
+  if (pages.some(page => path === page || path.startsWith(page + '/'))) {
+    return
+  }
+
+  // /@org/pkg or /pkg → /package/org/pkg or /package/pkg
+  let pkgMatch = path.match(/^\/(?:(?<org>@[^/]+)\/)?(?<name>[^/@]+)$/)
+  if (pkgMatch?.groups) {
+    const args = [pkgMatch.groups.org, pkgMatch.groups.name].filter(Boolean).join('/')
+    setHeader(event, 'cache-control', cacheControl)
+    return sendRedirect(event, `/package/${args}` + (query ? '?' + query : ''), 301)
+  }
+
+  // /@org/pkg/v/version or /@org/pkg@version → /package/org/pkg/v/version
+  // /pkg/v/version or /pkg@version → /package/pkg/v/version
+  const pkgVersionMatch =
+    path.match(/^\/(?:(?<org>@[^/]+)\/)?(?<name>[^/@]+)\/v\/(?<version>[^/]+)$/) ||
+    path.match(/^\/(?:(?<org>@[^/]+)\/)?(?<name>[^/@]+)@(?<version>[^/]+)$/)
+
+  if (pkgVersionMatch?.groups) {
+    const args = [pkgVersionMatch.groups.org, pkgVersionMatch.groups.name].filter(Boolean).join('/')
+    setHeader(event, 'cache-control', cacheControl)
+    return sendRedirect(
+      event,
+      `/package/${args}/v/${pkgVersionMatch.groups.version}` + (query ? '?' + query : ''),
+      301,
+    )
+  }
+
+  // /@org → /org/org
+  const orgMatch = path.match(/^\/@(?<org>[^/]+)$/)
+  if (orgMatch?.groups) {
+    setHeader(event, 'cache-control', cacheControl)
+    return sendRedirect(event, `/org/${orgMatch.groups.org}` + (query ? '?' + query : ''), 301)
+  }
+})

test/nuxt/a11y.spec.ts

···
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
···
           tree: mockTree,
           currentPath: 'src',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
···
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
···
           tree: mockTree,
           currentPath: 'src/index.ts',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
···
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)