From bfc5a57d3da74bedee2cec2c0500cea33ad09693 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 21:13:24 +0000
Subject: [PATCH 01/16] refactor: use object-syntax/named routes

---
 app/app.vue                                  |  2 +-
 app/components/AppFooter.vue                 |  4 ++--
 app/components/AppHeader.vue                 | 10 +++++-----
 app/components/Code/DirectoryListing.vue     | 19 ++++++++++++++++--
 app/components/Code/FileTree.vue             | 15 +++++++++++++-
 app/components/Code/MobileTreeDrawer.vue     |  9 ++++++++-
 app/components/Compare/ComparisonGrid.vue    |  2 +-
 app/components/Compare/PackageSelector.vue   |  2 +-
 app/components/Header/MobileMenu.client.vue  | 12 +++++------
 app/components/Header/OrgsDropdown.vue       |  6 +++---
 app/components/Header/PackagesDropdown.vue   |  6 +++---
 app/components/Package/ClaimPackageModal.vue |  4 ++--
 app/components/Package/TableRow.vue          |  5 ++++-
 app/components/Terminal/Install.vue          |  4 ++--
 app/components/VersionSelector.vue           |  2 +-
 app/pages/@[org].vue                         |  2 +-
 app/pages/package-code/[...path].vue         |  9 +++++++++
 app/pages/package-docs/[...path].vue         |  9 +++++++--
 app/pages/package/[...package].vue           | 21 ++++++++++++--------
 app/pages/privacy.vue                        |  4 ++--
 app/pages/~[username]/index.vue              |  2 +-
 app/pages/~[username]/orgs.vue               | 12 ++++++-----
 test/nuxt/a11y.spec.ts                       |  5 +++++
 23 files changed, 115 insertions(+), 51 deletions(-)

diff --git a/app/app.vue b/app/app.vue
index bc69bd9f0..bb95597ba 100644
--- a/app/app.vue
+++ b/app/app.vue
@@ -62,7 +62,7 @@ onKeyDown(
       return
     }
 
-    router.push('/search')
+    router.push({ name: 'search' })
   },
   { dedupe: true },
 )
diff --git a/app/components/AppFooter.vue b/app/components/AppFooter.vue
index 80565e73d..d8722a6f6 100644
--- a/app/components/AppFooter.vue
+++ b/app/components/AppFooter.vue
@@ -15,11 +15,11 @@ const isHome = computed(() => route.name === 'index')
         </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') }}
diff --git a/app/components/AppHeader.vue b/app/components/AppHeader.vue
index 05ebffb81..d4dd80d82 100644
--- a/app/components/AppHeader.vue
+++ b/app/components/AppHeader.vue
@@ -65,7 +65,7 @@ onKeyStroke(
   e => isKeyWithoutModifiers(e, ',') && !isEditableElement(e.target),
   e => {
     e.preventDefault()
-    navigateTo('/settings')
+    navigateTo({ name: 'settings' })
   },
   { dedupe: true },
 )
@@ -78,7 +78,7 @@ onKeyStroke(
     !e.defaultPrevented,
   e => {
     e.preventDefault()
-    navigateTo('/compare')
+    navigateTo({ name: 'compare' })
   },
   { dedupe: true },
 )
@@ -106,7 +106,7 @@ onKeyStroke(
       <!-- 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"
@@ -152,7 +152,7 @@ onKeyStroke(
       <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"
         >
@@ -167,7 +167,7 @@ onKeyStroke(
 
         <!-- 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=","
         >
diff --git a/app/components/Code/DirectoryListing.vue b/app/components/Code/DirectoryListing.vue
index 62e55bb0a..226a3a014 100644
--- a/app/components/Code/DirectoryListing.vue
+++ b/app/components/Code/DirectoryListing.vue
@@ -1,5 +1,6 @@
 <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'
 
@@ -7,6 +8,8 @@ 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[]
 }>()
 
 // Get the current directory's contents
@@ -36,6 +39,18 @@ const parentPath = computed(() => {
   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>
@@ -61,7 +76,7 @@ const parentPath = computed(() => {
         >
           <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" />
@@ -79,7 +94,7 @@ const parentPath = computed(() => {
         >
           <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'"
             >
diff --git a/app/components/Code/FileTree.vue b/app/components/Code/FileTree.vue
index 74e9bd8c8..5500098b1 100644
--- a/app/components/Code/FileTree.vue
+++ b/app/components/Code/FileTree.vue
@@ -1,11 +1,14 @@
 <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
 }>()
 
@@ -18,6 +21,15 @@ function isNodeActive(node: PackageFileTree): boolean {
   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)
 
 // Auto-expand directories in the current path
@@ -63,6 +75,7 @@ watch(
           :tree="node.children"
           :current-path="currentPath"
           :base-url="baseUrl"
+          :base-path="basePath"
           :depth="depth + 1"
         />
       </template>
@@ -70,7 +83,7 @@ watch(
       <!-- 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` }"
diff --git a/app/components/Code/MobileTreeDrawer.vue b/app/components/Code/MobileTreeDrawer.vue
index 2d3f6d04d..f7e7337f6 100644
--- a/app/components/Code/MobileTreeDrawer.vue
+++ b/app/components/Code/MobileTreeDrawer.vue
@@ -5,6 +5,8 @@ defineProps<{
   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)
@@ -73,7 +75,12 @@ watch(isOpen, open => (isLocked.value = open))
           <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>
diff --git a/app/components/Compare/ComparisonGrid.vue b/app/components/Compare/ComparisonGrid.vue
index 7f2ccf2d4..c2ee8dee1 100644
--- a/app/components/Compare/ComparisonGrid.vue
+++ b/app/components/Compare/ComparisonGrid.vue
@@ -45,7 +45,7 @@ function getReplacementTooltip(col: ComparisonGridColumn): string {
         >
           <span class="inline-flex items-center gap-1.5 truncate">
             <NuxtLink
-              :to="`/package/${col.header}`"
+              :to="{ name: 'package', params: { package: [col.header] } }"
               class="link-subtle font-mono text-sm font-medium text-fg truncate"
               :title="col.header"
             >
diff --git a/app/components/Compare/PackageSelector.vue b/app/components/Compare/PackageSelector.vue
index c2a87e36d..e977544a5 100644
--- a/app/components/Compare/PackageSelector.vue
+++ b/app/components/Compare/PackageSelector.vue
@@ -106,7 +106,7 @@ function handleBlur() {
         </template>
         <NuxtLink
           v-else
-          :to="`/package/${pkg}`"
+          :to="{ name: 'package', params: { package: [pkg] } }"
           class="font-mono text-sm text-fg hover:text-accent transition-colors"
         >
           {{ pkg }}
diff --git a/app/components/Header/MobileMenu.client.vue b/app/components/Header/MobileMenu.client.vue
index d62d7b7df..56e2312eb 100644
--- a/app/components/Header/MobileMenu.client.vue
+++ b/app/components/Header/MobileMenu.client.vue
@@ -104,7 +104,7 @@ onUnmounted(deactivate)
               <!-- 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"
                 >
@@ -113,7 +113,7 @@ onUnmounted(deactivate)
                 </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"
                 >
@@ -122,7 +122,7 @@ onUnmounted(deactivate)
                 </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"
                 >
@@ -131,7 +131,7 @@ onUnmounted(deactivate)
                 </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"
                 >
@@ -142,7 +142,7 @@ onUnmounted(deactivate)
                 <!-- 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"
                   >
@@ -151,7 +151,7 @@ onUnmounted(deactivate)
                   </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"
                   >
diff --git a/app/components/Header/OrgsDropdown.vue b/app/components/Header/OrgsDropdown.vue
index 50cd35991..222319c18 100644
--- a/app/components/Header/OrgsDropdown.vue
+++ b/app/components/Header/OrgsDropdown.vue
@@ -58,7 +58,7 @@ function handleKeydown(event: KeyboardEvent) {
     @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') }}
@@ -94,7 +94,7 @@ function handleKeydown(event: KeyboardEvent) {
           <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 }}
@@ -108,7 +108,7 @@ function handleKeydown(event: KeyboardEvent) {
 
           <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') }}
diff --git a/app/components/Header/PackagesDropdown.vue b/app/components/Header/PackagesDropdown.vue
index 37f030253..4dc7a73a6 100644
--- a/app/components/Header/PackagesDropdown.vue
+++ b/app/components/Header/PackagesDropdown.vue
@@ -58,7 +58,7 @@ function handleKeydown(event: KeyboardEvent) {
     @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') }}
@@ -94,7 +94,7 @@ function handleKeydown(event: KeyboardEvent) {
           <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="{ name: 'package', params: { package: [pkg] } }"
                 class="block px-3 py-2 font-mono text-sm text-fg hover:bg-bg-subtle transition-colors truncate"
               >
                 {{ pkg }}
@@ -108,7 +108,7 @@ function handleKeydown(event: KeyboardEvent) {
 
           <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') }}
diff --git a/app/components/Package/ClaimPackageModal.vue b/app/components/Package/ClaimPackageModal.vue
index ce8d48d7e..1272ed2e7 100644
--- a/app/components/Package/ClaimPackageModal.vue
+++ b/app/components/Package/ClaimPackageModal.vue
@@ -173,7 +173,7 @@ const previewPackageJson = computed(() => {
 
       <div class="flex gap-3">
         <NuxtLink
-          :to="`/package/${packageName}`"
+          :to="{ name: 'package', params: { package: [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"
         >
@@ -277,7 +277,7 @@ const previewPackageJson = computed(() => {
               <span v-else class="w-4 h-4 shrink-0" />
               <div class="min-w-0">
                 <NuxtLink
-                  :to="`/package/${pkg.name}`"
+                  :to="{ name: 'package', params: { package: [pkg.name] } }"
                   class="font-mono text-sm text-fg hover:underline focus-visible:outline-accent/70 rounded"
                   target="_blank"
                 >
diff --git a/app/components/Package/TableRow.vue b/app/components/Package/TableRow.vue
index cf4ea0ea4..2330dca04 100644
--- a/app/components/Package/TableRow.vue
+++ b/app/components/Package/TableRow.vue
@@ -106,7 +106,10 @@ const allMaintainersText = computed(() => {
           :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
diff --git a/app/components/Terminal/Install.vue b/app/components/Terminal/Install.vue
index b03a5d6fa..50ab67abc 100644
--- a/app/components/Terminal/Install.vue
+++ b/app/components/Terminal/Install.vue
@@ -149,7 +149,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               ></code
             >
             <NuxtLink
-              :to="`/package/${typesPackageName}`"
+              :to="{ name: 'package', params: { package: [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 })"
             >
@@ -202,7 +202,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               :text="$t('package.create.view', { packageName: createPackageInfo.packageName })"
             >
               <NuxtLink
-                :to="`/package/${createPackageInfo.packageName}`"
+                :to="{ name: 'package', params: { package: [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" />
diff --git a/app/components/VersionSelector.vue b/app/components/VersionSelector.vue
index 9721825ed..7278492ea 100644
--- a/app/components/VersionSelector.vue
+++ b/app/components/VersionSelector.vue
@@ -620,7 +620,7 @@ watch(
         <!-- 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="{ name: 'package', params: { package: [packageName] } }"
             class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
             @click="isOpen = false"
           >
diff --git a/app/pages/@[org].vue b/app/pages/@[org].vue
index f91fc3b4b..c040e7aa3 100644
--- a/app/pages/@[org].vue
+++ b/app/pages/@[org].vue
@@ -245,7 +245,7 @@ defineOgImageComponent('Default', {
       <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 -->
diff --git a/app/pages/package-code/[...path].vue b/app/pages/package-code/[...path].vue
index cd32c86c2..62815b13d 100644
--- a/app/pages/package-code/[...path].vue
+++ b/app/pages/package-code/[...path].vue
@@ -198,6 +198,12 @@ function getCodeUrl(path?: string): string {
   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
@@ -398,6 +404,7 @@ defineOgImageComponent('Default', {
           :tree="fileTree.tree"
           :current-path="filePath ?? ''"
           :base-url="getCodeUrl()"
+          :base-path="basePath"
         />
       </aside>
 
@@ -557,6 +564,7 @@ defineOgImageComponent('Default', {
             :tree="fileTree.tree"
             :current-path="filePath ?? ''"
             :base-url="getCodeUrl()"
+            :base-path="basePath"
           />
         </template>
       </div>
@@ -570,6 +578,7 @@ defineOgImageComponent('Default', {
           :tree="fileTree.tree"
           :current-path="filePath ?? ''"
           :base-url="getCodeUrl()"
+          :base-path="basePath"
         />
       </Teleport>
     </ClientOnly>
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index bc16154ea..602939aeb 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -46,8 +46,12 @@ if (import.meta.server && !requestedVersion.value && packageName.value) {
   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 },
+      ),
     )
   }
 }
@@ -56,7 +60,8 @@ watch(
   [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 },
diff --git a/app/pages/package/[...package].vue b/app/pages/package/[...package].vue
index ac08f83a1..670feb076 100644
--- a/app/pages/package/[...package].vue
+++ b/app/pages/package/[...package].vue
@@ -318,7 +318,12 @@ const homepageUrl = computed(() => {
 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(() => {
@@ -493,7 +498,7 @@ onKeyStroke(
   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>
@@ -559,7 +564,7 @@ onKeyStroke(
 
             <NuxtLink
               v-if="requestedVersion && resolvedVersion !== requestedVersion"
-              :to="`/package/${pkg.name}/v/${resolvedVersion}`"
+              :to="{ name: 'package', params: { package: [pkg.name, 'v', resolvedVersion] } }"
               :title="$t('package.view_permalink')"
               >{{ resolvedVersion }}</NuxtLink
             >
@@ -670,7 +675,7 @@ onKeyStroke(
               </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="."
             >
@@ -684,7 +689,7 @@ onKeyStroke(
               </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"
             >
@@ -821,7 +826,7 @@ onKeyStroke(
             </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" />
@@ -830,7 +835,7 @@ onKeyStroke(
             </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" />
@@ -1266,7 +1271,7 @@ onKeyStroke(
       <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>
diff --git a/app/pages/privacy.vue b/app/pages/privacy.vue
index d42750163..ef013f344 100644
--- a/app/pages/privacy.vue
+++ b/app/pages/privacy.vue
@@ -138,7 +138,7 @@ const { locale } = useI18n()
               </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') }}
@@ -266,7 +266,7 @@ const { locale } = useI18n()
             <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') }}
diff --git a/app/pages/~[username]/index.vue b/app/pages/~[username]/index.vue
index 224d24f41..aa37a7283 100644
--- a/app/pages/~[username]/index.vue
+++ b/app/pages/~[username]/index.vue
@@ -228,7 +228,7 @@ defineOgImageComponent('Default', {
       <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 -->
diff --git a/app/pages/~[username]/orgs.vue b/app/pages/~[username]/orgs.vue
index 6a1654ceb..a88dbdc6e 100644
--- a/app/pages/~[username]/orgs.vue
+++ b/app/pages/~[username]/orgs.vue
@@ -134,7 +134,7 @@ defineOgImageComponent('Default', {
       <!-- 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"
         >
@@ -158,9 +158,11 @@ defineOgImageComponent('Default', {
       <!-- 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 -->
@@ -189,7 +191,7 @@ defineOgImageComponent('Default', {
         <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">
diff --git a/test/nuxt/a11y.spec.ts b/test/nuxt/a11y.spec.ts
index 97acc65b2..9164dfb8c 100644
--- a/test/nuxt/a11y.spec.ts
+++ b/test/nuxt/a11y.spec.ts
@@ -839,6 +839,7 @@ describe('component accessibility audits', () => {
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
@@ -851,6 +852,7 @@ describe('component accessibility audits', () => {
           tree: mockTree,
           currentPath: 'src',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
@@ -875,6 +877,7 @@ describe('component accessibility audits', () => {
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
@@ -887,6 +890,7 @@ describe('component accessibility audits', () => {
           tree: mockTree,
           currentPath: 'src/index.ts',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)
@@ -1136,6 +1140,7 @@ describe('component accessibility audits', () => {
           tree: mockTree,
           currentPath: '',
           baseUrl: '/package-code/vue',
+          basePath: ['vue', 'v', '3.0.0'],
         },
       })
       const results = await runAxe(component)

From b6d27e2fcca168d2b8d5399e53ba35d48578a2bb Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:14:55 +0000
Subject: [PATCH 02/16] refactor: use `/package/` and `/org` prefixes by
 default

---
 app/components/Compare/ComparisonGrid.vue     |  2 +-
 app/components/Compare/PackageSelector.vue    |  2 +-
 app/components/DependencyPathPopup.vue        | 16 ++----
 app/components/Header/PackagesDropdown.vue    |  2 +-
 app/components/Package/Card.vue               |  2 +-
 app/components/Package/ClaimPackageModal.vue  |  4 +-
 app/components/Package/Dependencies.vue       | 34 +++--------
 app/components/Package/DeprecatedTree.vue     |  5 +-
 app/components/Package/InstallScripts.vue     |  2 +-
 app/components/Package/TableRow.vue           |  2 +-
 app/components/Package/Versions.vue           |  5 +-
 app/components/Package/VulnerabilityTree.vue  |  5 +-
 app/components/Terminal/Install.vue           |  4 +-
 app/components/VersionSelector.vue            |  2 +-
 app/composables/usePackageRoute.ts            | 56 ++++---------------
 app/middleware/canonical-redirects.global.ts  | 49 ----------------
 app/pages/index.vue                           |  2 +-
 app/pages/{@[org].vue => org/[org].vue}       |  1 -
 app/pages/package-code/[...path].vue          | 19 +++----
 app/pages/package-docs/[...path].vue          |  4 +-
 .../{[...package].vue => [[org]]/[name].vue}  |  7 +--
 app/pages/package/[[org]]/[name]/index.vue    | 10 ++++
 .../package/[[org]]/[name]/v/[version].vue    | 10 ++++
 app/pages/search.vue                          |  5 +-
 app/utils/router.ts                           | 24 ++++++++
 nuxt.config.ts                                | 34 ++++++-----
 .../middleware/canonical-redirects.global.ts  | 37 ++++++++++++
 27 files changed, 148 insertions(+), 197 deletions(-)
 delete mode 100644 app/middleware/canonical-redirects.global.ts
 rename app/pages/{@[org].vue => org/[org].vue} (99%)
 rename app/pages/package/{[...package].vue => [[org]]/[name].vue} (99%)
 create mode 100644 app/pages/package/[[org]]/[name]/index.vue
 create mode 100644 app/pages/package/[[org]]/[name]/v/[version].vue
 create mode 100644 app/utils/router.ts
 create mode 100644 server/middleware/canonical-redirects.global.ts

diff --git a/app/components/Compare/ComparisonGrid.vue b/app/components/Compare/ComparisonGrid.vue
index c2ee8dee1..ffa69a29b 100644
--- a/app/components/Compare/ComparisonGrid.vue
+++ b/app/components/Compare/ComparisonGrid.vue
@@ -45,7 +45,7 @@ function getReplacementTooltip(col: ComparisonGridColumn): string {
         >
           <span class="inline-flex items-center gap-1.5 truncate">
             <NuxtLink
-              :to="{ name: 'package', params: { package: [col.header] } }"
+              :to="packageRoute(col.header)"
               class="link-subtle font-mono text-sm font-medium text-fg truncate"
               :title="col.header"
             >
diff --git a/app/components/Compare/PackageSelector.vue b/app/components/Compare/PackageSelector.vue
index e977544a5..d81fa964b 100644
--- a/app/components/Compare/PackageSelector.vue
+++ b/app/components/Compare/PackageSelector.vue
@@ -106,7 +106,7 @@ function handleBlur() {
         </template>
         <NuxtLink
           v-else
-          :to="{ name: 'package', params: { package: [pkg] } }"
+          :to="packageRoute(pkg)"
           class="font-mono text-sm text-fg hover:text-accent transition-colors"
         >
           {{ pkg }}
diff --git a/app/components/DependencyPathPopup.vue b/app/components/DependencyPathPopup.vue
index 08d0e2958..780637286 100644
--- a/app/components/DependencyPathPopup.vue
+++ b/app/components/DependencyPathPopup.vue
@@ -93,16 +93,12 @@ function parsePackageString(pkg: string): { name: string; version: string } {
           >
             <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"
diff --git a/app/components/Header/PackagesDropdown.vue b/app/components/Header/PackagesDropdown.vue
index 4dc7a73a6..ddd9f86d5 100644
--- a/app/components/Header/PackagesDropdown.vue
+++ b/app/components/Header/PackagesDropdown.vue
@@ -94,7 +94,7 @@ function handleKeydown(event: KeyboardEvent) {
           <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="{ name: 'package', params: { 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 }}
diff --git a/app/components/Package/Card.vue b/app/components/Package/Card.vue
index 7b96c5d92..a46f10628 100644
--- a/app/components/Package/Card.vue
+++ b/app/components/Package/Card.vue
@@ -44,7 +44,7 @@ const pkgDescription = useMarkdown(() => ({
         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"
diff --git a/app/components/Package/ClaimPackageModal.vue b/app/components/Package/ClaimPackageModal.vue
index 1272ed2e7..bf4771214 100644
--- a/app/components/Package/ClaimPackageModal.vue
+++ b/app/components/Package/ClaimPackageModal.vue
@@ -173,7 +173,7 @@ const previewPackageJson = computed(() => {
 
       <div class="flex gap-3">
         <NuxtLink
-          :to="{ name: 'package', params: { 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"
         >
@@ -277,7 +277,7 @@ const previewPackageJson = computed(() => {
               <span v-else class="w-4 h-4 shrink-0" />
               <div class="min-w-0">
                 <NuxtLink
-                  :to="{ name: 'package', params: { package: [pkg.name] } }"
+                  :to="packageRoute(pkg.name)"
                   class="font-mono text-sm text-fg hover:underline focus-visible:outline-accent/70 rounded"
                   target="_blank"
                 >
diff --git a/app/components/Package/Dependencies.vue b/app/components/Package/Dependencies.vue
index 965a67712..6366c45d3 100644
--- a/app/components/Package/Dependencies.vue
+++ b/app/components/Package/Dependencies.vue
@@ -82,7 +82,7 @@ const sortedOptionalDependencies = computed(() => {
           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 }}
@@ -99,10 +99,7 @@ const sortedOptionalDependencies = computed(() => {
             </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`"
@@ -112,10 +109,7 @@ const sortedOptionalDependencies = computed(() => {
             </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"
             >
@@ -123,10 +117,7 @@ const sortedOptionalDependencies = computed(() => {
               <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"
@@ -174,10 +165,7 @@ const sortedOptionalDependencies = computed(() => {
         >
           <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 }}
@@ -191,10 +179,7 @@ const sortedOptionalDependencies = computed(() => {
             </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"
           >
@@ -239,16 +224,13 @@ const sortedOptionalDependencies = computed(() => {
           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"
           >
diff --git a/app/components/Package/DeprecatedTree.vue b/app/components/Package/DeprecatedTree.vue
index 3521876eb..f78d90b29 100644
--- a/app/components/Package/DeprecatedTree.vue
+++ b/app/components/Package/DeprecatedTree.vue
@@ -84,10 +84,7 @@ function getDepthStyle(depth: DependencyDepth) {
               <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"
               >
diff --git a/app/components/Package/InstallScripts.vue b/app/components/Package/InstallScripts.vue
index dde493782..ba314a4c0 100644
--- a/app/components/Package/InstallScripts.vue
+++ b/app/components/Package/InstallScripts.vue
@@ -73,7 +73,7 @@ const isExpanded = shallowRef(false)
           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 }}
diff --git a/app/components/Package/TableRow.vue b/app/components/Package/TableRow.vue
index 2330dca04..25b895a9f 100644
--- a/app/components/Package/TableRow.vue
+++ b/app/components/Package/TableRow.vue
@@ -34,7 +34,7 @@ function isColumnVisible(id: string): boolean {
   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 ''
diff --git a/app/components/Package/Versions.vue b/app/components/Package/Versions.vue
index 9461da3d8..cb4010b46 100644
--- a/app/components/Package/Versions.vue
+++ b/app/components/Package/Versions.vue
@@ -33,10 +33,7 @@ interface VersionDisplay {
 
 // 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)
diff --git a/app/components/Package/VulnerabilityTree.vue b/app/components/Package/VulnerabilityTree.vue
index 9b505ea0d..7a3d6f2a6 100644
--- a/app/components/Package/VulnerabilityTree.vue
+++ b/app/components/Package/VulnerabilityTree.vue
@@ -113,10 +113,7 @@ function getDepthStyle(depth: string | undefined) {
                 <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"
                 >
diff --git a/app/components/Terminal/Install.vue b/app/components/Terminal/Install.vue
index 50ab67abc..cfa902ce4 100644
--- a/app/components/Terminal/Install.vue
+++ b/app/components/Terminal/Install.vue
@@ -149,7 +149,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               ></code
             >
             <NuxtLink
-              :to="{ name: 'package', params: { 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 })"
             >
@@ -202,7 +202,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               :text="$t('package.create.view', { packageName: createPackageInfo.packageName })"
             >
               <NuxtLink
-                :to="{ name: 'package', params: { 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" />
diff --git a/app/components/VersionSelector.vue b/app/components/VersionSelector.vue
index 7278492ea..a8f8fc4b4 100644
--- a/app/components/VersionSelector.vue
+++ b/app/components/VersionSelector.vue
@@ -620,7 +620,7 @@ watch(
         <!-- Link to package page for full version list -->
         <div class="border-t border-border mt-1 pt-1 px-3 py-2">
           <NuxtLink
-            :to="{ name: 'package', params: { 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"
           >
diff --git a/app/composables/usePackageRoute.ts b/app/composables/usePackageRoute.ts
index ee4a4a143..72458ba2c 100644
--- a/app/composables/usePackageRoute.ts
+++ b/app/composables/usePackageRoute.ts
@@ -1,56 +1,22 @@
 /**
  * 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 route = useRoute<'package'>('package')
 
-  const parsedRoute = computed(() => {
-    const segments = route.params.package?.filter(Boolean) || []
-
-    // 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 orgName = computed(() => {
-    const name = packageName.value
-    if (!name.startsWith('@')) return null
-    const match = name.match(/^@([^/]+)\//)
-    return match ? match[1] : null
-  })
+  const requestedVersion = computed(() => ('version' in route.params ? route.params.version : null))
+  const orgName = computed(() => route.params.org ?? null)
 
   return {
     packageName,
diff --git a/app/middleware/canonical-redirects.global.ts b/app/middleware/canonical-redirects.global.ts
deleted file mode 100644
index 549a1b35c..000000000
--- a/app/middleware/canonical-redirects.global.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-/**
- * 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 })
-    }
-  }
-})
diff --git a/app/pages/index.vue b/app/pages/index.vue
index f9c97f0c2..6e8f2cd66 100644
--- a/app/pages/index.vue
+++ b/app/pages/index.vue
@@ -124,7 +124,7 @@ defineOgImageComponent('Default', {
         <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
diff --git a/app/pages/@[org].vue b/app/pages/org/[org].vue
similarity index 99%
rename from app/pages/@[org].vue
rename to app/pages/org/[org].vue
index c040e7aa3..13f0c7fca 100644
--- a/app/pages/@[org].vue
+++ b/app/pages/org/[org].vue
@@ -5,7 +5,6 @@ import { debounce } from 'perfect-debounce'
 
 definePageMeta({
   name: 'org',
-  alias: ['/org/:org()'],
 })
 
 const route = useRoute('org')
diff --git a/app/pages/package-code/[...path].vue b/app/pages/package-code/[...path].vue
index 62815b13d..ee3a1a708 100644
--- a/app/pages/package-code/[...path].vue
+++ b/app/pages/package-code/[...path].vue
@@ -212,15 +212,6 @@ const orgName = computed(() => {
   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
@@ -321,7 +312,7 @@ defineOgImageComponent('Default', {
         <!-- 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"
           >
@@ -379,7 +370,9 @@ defineOgImageComponent('Default', {
     <!-- 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 -->
@@ -391,7 +384,9 @@ defineOgImageComponent('Default', {
     <!-- 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 -->
diff --git a/app/pages/package-docs/[...path].vue b/app/pages/package-docs/[...path].vue
index 602939aeb..d88f12ff3 100644
--- a/app/pages/package-docs/[...path].vue
+++ b/app/pages/package-docs/[...path].vue
@@ -132,7 +132,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
           <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 }}
@@ -191,7 +191,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
             <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
diff --git a/app/pages/package/[...package].vue b/app/pages/package/[[org]]/[name].vue
similarity index 99%
rename from app/pages/package/[...package].vue
rename to app/pages/package/[[org]]/[name].vue
index 670feb076..565af607b 100644
--- a/app/pages/package/[...package].vue
+++ b/app/pages/package/[[org]]/[name].vue
@@ -18,11 +18,6 @@ import { useModal } from '~/composables/useModal'
 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 ?? '',
@@ -564,7 +559,7 @@ onKeyStroke(
 
             <NuxtLink
               v-if="requestedVersion && resolvedVersion !== requestedVersion"
-              :to="{ name: 'package', params: { package: [pkg.name, 'v', resolvedVersion] } }"
+              :to="packageRoute(pkg.name, resolvedVersion)"
               :title="$t('package.view_permalink')"
               >{{ resolvedVersion }}</NuxtLink
             >
diff --git a/app/pages/package/[[org]]/[name]/index.vue b/app/pages/package/[[org]]/[name]/index.vue
new file mode 100644
index 000000000..20f211960
--- /dev/null
+++ b/app/pages/package/[[org]]/[name]/index.vue
@@ -0,0 +1,10 @@
+<script setup lang="ts">
+// stub page to help with paths
+definePageMeta({
+  name: 'package',
+})
+</script>
+
+<template>
+  <div />
+</template>
diff --git a/app/pages/package/[[org]]/[name]/v/[version].vue b/app/pages/package/[[org]]/[name]/v/[version].vue
new file mode 100644
index 000000000..863bbe77d
--- /dev/null
+++ b/app/pages/package/[[org]]/[name]/v/[version].vue
@@ -0,0 +1,10 @@
+<script setup lang="ts">
+// stub page to help with paths
+definePageMeta({
+  name: 'package-version',
+})
+</script>
+
+<template>
+  <div />
+</template>
diff --git a/app/pages/search.vue b/app/pages/search.vue
index 2faf3f3be..85868990b 100644
--- a/app/pages/search.vue
+++ b/app/pages/search.vue
@@ -543,10 +543,7 @@ function focusElement(el: HTMLElement) {
 
 // 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)
diff --git a/app/utils/router.ts b/app/utils/router.ts
new file mode 100644
index 000000000..7fcf5c917
--- /dev/null
+++ b/app/utils/router.ts
@@ -0,0 +1,24 @@
+export function packageRoute(packageName: string, version?: string | null) {
+  const [org, name] = packageName.startsWith('@')
+    ? packageName.slice(1).split('/')
+    : [null, packageName]
+
+  if (version) {
+    return {
+      name: 'package-version' as const,
+      params: {
+        org,
+        name,
+        version,
+      },
+    }
+  }
+
+  return {
+    name: 'package' as const,
+    params: {
+      org,
+      name,
+    },
+  }
+}
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 54ba28333..4051d8b0d 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -85,17 +85,19 @@ export default defineNuxtConfig({
   },
 
   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': {
@@ -105,24 +107,20 @@ export default defineNuxtConfig({
         allowQuery: ['q'],
       },
     },
+    // pages
+    '/package/:scope/:name': { isr: getISRConfig(60, true) },
+    '/package/:scope/: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/**',
-      },
-    },
     // 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' },
diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
new file mode 100644
index 000000000..5d9178a78
--- /dev/null
+++ b/server/middleware/canonical-redirects.global.ts
@@ -0,0 +1,37 @@
+/**
+ * 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 defineEventHandler(async event => {
+  const path = event.path
+
+  // /@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('/')
+    return sendRedirect(event, `/package/${args}`)
+  }
+
+  // /@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('/')
+    return sendRedirect(event, `/package/${args}/v/${pkgVersionMatch.groups.version}`)
+  }
+
+  // /org/* → /@*
+  const orgMatch = path.match(/^\/@(?<org>[^/]+)$/)
+  if (orgMatch?.groups) {
+    return sendRedirect(event, `/org/${orgMatch.groups.org}`)
+  }
+})

From e819407db778e04145bdb32d45f8074da522bd5b Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:28:49 +0000
Subject: [PATCH 03/16] fix: update isr fallback paths

---
 .gitignore              | 3 +++
 modules/isr-fallback.ts | 5 +++--
 nuxt.config.ts          | 8 ++++----
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 45734458b..12ca103c2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,6 @@ test-results/
 
 # generated files
 shared/types/lexicons
+
+# output
+.vercel
diff --git a/modules/isr-fallback.ts b/modules/isr-fallback.ts
index 6125d2cf7..811aac97b 100644
--- a/modules/isr-fallback.ts
+++ b/modules/isr-fallback.ts
@@ -1,4 +1,4 @@
-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'
@@ -15,13 +15,14 @@ export default defineNuxtModule({
     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/[org]/[name]', '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)
         }
       })
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 4051d8b0d..460ab8943 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -108,12 +108,12 @@ export default defineNuxtConfig({
       },
     },
     // pages
-    '/package/:scope/:name': { isr: getISRConfig(60, true) },
-    '/package/:scope/: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 } },
+    '/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 },

From 5a17966d14f069fb04d9fb0a0d46ecae55edb22e Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:32:05 +0000
Subject: [PATCH 04/16] chore: once more

---
 modules/isr-fallback.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/modules/isr-fallback.ts b/modules/isr-fallback.ts
index 811aac97b..f31af9e40 100644
--- a/modules/isr-fallback.ts
+++ b/modules/isr-fallback.ts
@@ -15,7 +15,12 @@ export default defineNuxtModule({
     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/[org]/[name]', 'package/[org]/[name]/v/[version]', '']) {
+        for (const path of [
+          'package/[org]/[name]',
+          'package/[org]/[name]/v',
+          'package/[org]/[name]/v/[version]',
+          '',
+        ]) {
           const outputPath = resolve(
             nitro.options.output.serverDir,
             '..',

From 1d8e02fe0090b8174d6d07a48c428440b0d8ed36 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:34:42 +0000
Subject: [PATCH 05/16] fix: redirects

---
 .../middleware/canonical-redirects.global.ts  | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 5d9178a78..f9c320045 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -8,9 +8,29 @@
  * - /org/* → /@*
  * - /* → /package/* (Unless it's an existing page)
  */
+const pages = [
+  '/about',
+  '/compare',
+  '/org',
+  '/package',
+  '/package-code',
+  '/package-docs',
+  '/privacy',
+  '/search',
+  '/settings',
+]
 export default defineEventHandler(async event => {
   const path = event.path
 
+  // username
+  if (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) {

From b127c62903fd7de59a6b6ac737ad7b75c1f4c5a6 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:38:06 +0000
Subject: [PATCH 06/16] chore: one more

---
 modules/isr-fallback.ts                         | 1 +
 server/middleware/canonical-redirects.global.ts | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/modules/isr-fallback.ts b/modules/isr-fallback.ts
index f31af9e40..cf58c1853 100644
--- a/modules/isr-fallback.ts
+++ b/modules/isr-fallback.ts
@@ -16,6 +16,7 @@ export default defineNuxtModule({
       nitro.hooks.hook('compiled', () => {
         const spaTemplate = readFileSync(nitro.options.output.publicDir + '/200.html', 'utf-8')
         for (const path of [
+          'package/[org]',
           'package/[org]/[name]',
           'package/[org]/[name]/v',
           'package/[org]/[name]/v/[version]',
diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index f9c320045..41403cd82 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -20,7 +20,7 @@ const pages = [
   '/settings',
 ]
 export default defineEventHandler(async event => {
-  const path = event.path
+  const path = event.path.split('?')[0]!
 
   // username
   if (path.startsWith('~')) {

From ea9a4017d45bf856c7b92476c9584a435b7c0974 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:42:56 +0000
Subject: [PATCH 07/16] fix: change unscoped packages too

---
 modules/isr-fallback.ts | 4 ++++
 nuxt.config.ts          | 2 ++
 2 files changed, 6 insertions(+)

diff --git a/modules/isr-fallback.ts b/modules/isr-fallback.ts
index cf58c1853..13a7f92fe 100644
--- a/modules/isr-fallback.ts
+++ b/modules/isr-fallback.ts
@@ -16,6 +16,10 @@ export default defineNuxtModule({
       nitro.hooks.hook('compiled', () => {
         const spaTemplate = readFileSync(nitro.options.output.publicDir + '/200.html', 'utf-8')
         for (const path of [
+          'package',
+          'package/[name]',
+          'package/[name]/v',
+          'package/[name]/v/[version]',
           'package/[org]',
           'package/[org]/[name]',
           'package/[org]/[name]/v',
diff --git a/nuxt.config.ts b/nuxt.config.ts
index 460ab8943..2b7207723 100644
--- a/nuxt.config.ts
+++ b/nuxt.config.ts
@@ -108,6 +108,8 @@ export default defineNuxtConfig({
       },
     },
     // 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)

From ddb61e977a5c8ff6293e44442bf243d37e3377c7 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:55:43 +0000
Subject: [PATCH 08/16] fix: correct username prefix

---
 server/middleware/canonical-redirects.global.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 41403cd82..947e68cbe 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -23,7 +23,7 @@ export default defineEventHandler(async event => {
   const path = event.path.split('?')[0]!
 
   // username
-  if (path.startsWith('~')) {
+  if (path.startsWith('/~')) {
     return
   }
 

From 3cc2025d3b4ea758eec2872338e9a22bf331766e Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Thu, 5 Feb 2026 22:58:38 +0000
Subject: [PATCH 09/16] chore: update comment

---
 server/middleware/canonical-redirects.global.ts | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 947e68cbe..02ef94724 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -1,12 +1,16 @@
 /**
- * Redirect legacy URLs to canonical paths (client-side only)
+ * 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/*
+ * - /code/*         → /package-code/*
  * - /package/docs/* → /package-docs/*
- * - /docs/* → /package-docs/*
- * - /org/* → /@*
- * - /* → /package/* (Unless it's an existing page)
+ * - /docs/*         → /package-docs/*
  */
 const pages = [
   '/about',
@@ -49,7 +53,7 @@ export default defineEventHandler(async event => {
     return sendRedirect(event, `/package/${args}/v/${pkgVersionMatch.groups.version}`)
   }
 
-  // /org/* → /@*
+  // /@org → /org/org
   const orgMatch = path.match(/^\/@(?<org>[^/]+)$/)
   if (orgMatch?.groups) {
     return sendRedirect(event, `/org/${orgMatch.groups.org}`)

From 32f13fbc65707f0220fcfe0e4b8a489d91a8d25f Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 08:24:34 +0000
Subject: [PATCH 10/16] fix: include `@` in org param

---
 app/composables/usePackageRoute.ts | 11 +++++++----
 app/utils/router.ts                |  4 +---
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/app/composables/usePackageRoute.ts b/app/composables/usePackageRoute.ts
index 72458ba2c..abf3d28a8 100644
--- a/app/composables/usePackageRoute.ts
+++ b/app/composables/usePackageRoute.ts
@@ -3,20 +3,23 @@
  *
  * Routes use structured params:
  *   /package/nuxt → org: undefined, name: "nuxt"
- *   /package/@nuxt/kit → org: "nuxt", name: "kit"
+ *   /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"
+ *   /package/@nuxt/kit/v/1.0.0 → org: "@nuxt", name: "kit", version: "1.0.0"
  */
 export function usePackageRoute() {
   const route = useRoute<'package'>('package')
 
   const packageName = computed(() => {
     const { org, name } = route.params
-    return org ? `@${org}/${name}` : name
+    return org ? `${org}/${name}` : name
   })
 
   const requestedVersion = computed(() => ('version' in route.params ? route.params.version : null))
-  const orgName = computed(() => route.params.org ?? null)
+  const orgName = computed(() => {
+    const org = route.params.org
+    return org ? org.replace(/^@/, '') : null
+  })
 
   return {
     packageName,
diff --git a/app/utils/router.ts b/app/utils/router.ts
index 7fcf5c917..42bff5eda 100644
--- a/app/utils/router.ts
+++ b/app/utils/router.ts
@@ -1,7 +1,5 @@
 export function packageRoute(packageName: string, version?: string | null) {
-  const [org, name] = packageName.startsWith('@')
-    ? packageName.slice(1).split('/')
-    : [null, packageName]
+  const [org, name] = packageName.startsWith('@') ? packageName.split('/') : [null, packageName]
 
   if (version) {
     return {

From 1657bff1c51325d281e3fc94269cfa8e69004c39 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 08:25:53 +0000
Subject: [PATCH 11/16] fix: do not redirect named paths

---
 server/middleware/canonical-redirects.global.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 02ef94724..8a3e77b38 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -24,6 +24,11 @@ const pages = [
   '/settings',
 ]
 export default defineEventHandler(async event => {
+  const routeRules = getRouteRules(event)
+  if (Object.keys(routeRules).length > 1) {
+    return
+  }
+
   const path = event.path.split('?')[0]!
 
   // username

From 4690b1a604ea3beb8750a1239f9bb3a324222a59 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 08:29:47 +0000
Subject: [PATCH 12/16] fix: don't redirect for nuxt erros

---
 server/middleware/canonical-redirects.global.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 8a3e77b38..19889682c 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -32,7 +32,7 @@ export default defineEventHandler(async event => {
   const path = event.path.split('?')[0]!
 
   // username
-  if (path.startsWith('/~')) {
+  if (path.startsWith('/~') || path.startsWith('/_')) {
     return
   }
 

From 2c15c092f3a670016f9dc2c6eb8bd53810fd2d85 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 08:31:58 +0000
Subject: [PATCH 13/16] perf: set `stale-while-revalidate` header

---
 server/middleware/canonical-redirects.global.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 19889682c..a7aab726c 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -44,6 +44,7 @@ export default defineEventHandler(async event => {
   let pkgMatch = path.match(/^\/(?:(?<org>@[^/]+)\/)?(?<name>[^/@]+)$/)
   if (pkgMatch?.groups) {
     const args = [pkgMatch.groups.org, pkgMatch.groups.name].filter(Boolean).join('/')
+    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
     return sendRedirect(event, `/package/${args}`)
   }
 
@@ -55,12 +56,14 @@ export default defineEventHandler(async event => {
 
   if (pkgVersionMatch?.groups) {
     const args = [pkgVersionMatch.groups.org, pkgVersionMatch.groups.name].filter(Boolean).join('/')
+    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
     return sendRedirect(event, `/package/${args}/v/${pkgVersionMatch.groups.version}`)
   }
 
   // /@org → /org/org
   const orgMatch = path.match(/^\/@(?<org>[^/]+)$/)
   if (orgMatch?.groups) {
+    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
     return sendRedirect(event, `/org/${orgMatch.groups.org}`)
   }
 })

From 7decbcdf467f664cc8f51a5b7ec7d3f6e2e24399 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 09:34:36 +0000
Subject: [PATCH 14/16] perf: lengthen cache

---
 server/middleware/canonical-redirects.global.ts | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index a7aab726c..1b0417f39 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -23,6 +23,9 @@ const pages = [
   '/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) {
@@ -44,8 +47,8 @@ export default defineEventHandler(async event => {
   let pkgMatch = path.match(/^\/(?:(?<org>@[^/]+)\/)?(?<name>[^/@]+)$/)
   if (pkgMatch?.groups) {
     const args = [pkgMatch.groups.org, pkgMatch.groups.name].filter(Boolean).join('/')
-    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
-    return sendRedirect(event, `/package/${args}`)
+    setHeader(event, 'cache-control', cacheControl)
+    return sendRedirect(event, `/package/${args}`, 301)
   }
 
   // /@org/pkg/v/version or /@org/pkg@version → /package/org/pkg/v/version
@@ -56,14 +59,14 @@ export default defineEventHandler(async event => {
 
   if (pkgVersionMatch?.groups) {
     const args = [pkgVersionMatch.groups.org, pkgVersionMatch.groups.name].filter(Boolean).join('/')
-    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
+    setHeader(event, 'cache-control', cacheControl)
     return sendRedirect(event, `/package/${args}/v/${pkgVersionMatch.groups.version}`)
   }
 
   // /@org → /org/org
   const orgMatch = path.match(/^\/@(?<org>[^/]+)$/)
   if (orgMatch?.groups) {
-    setHeader(event, 'cache-control', 'stale-while-revalidate=31536000, public')
+    setHeader(event, 'cache-control', cacheControl)
     return sendRedirect(event, `/org/${orgMatch.groups.org}`)
   }
 })

From 3e69d3e3499fce68a0f757ed007a6839312500d2 Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 11:14:31 +0000
Subject: [PATCH 15/16] fix: include query in redirect

---
 server/middleware/canonical-redirects.global.ts | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index 1b0417f39..f0e16afea 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -32,7 +32,7 @@ export default defineEventHandler(async event => {
     return
   }
 
-  const path = event.path.split('?')[0]!
+  const [path = '/', query] = event.path.split('?')
 
   // username
   if (path.startsWith('/~') || path.startsWith('/_')) {
@@ -48,7 +48,7 @@ export default defineEventHandler(async event => {
   if (pkgMatch?.groups) {
     const args = [pkgMatch.groups.org, pkgMatch.groups.name].filter(Boolean).join('/')
     setHeader(event, 'cache-control', cacheControl)
-    return sendRedirect(event, `/package/${args}`, 301)
+    return sendRedirect(event, `/package/${args}` + (query ? '?' + query : ''), 301)
   }
 
   // /@org/pkg/v/version or /@org/pkg@version → /package/org/pkg/v/version
@@ -60,13 +60,17 @@ export default defineEventHandler(async event => {
   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}`)
+    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}`)
+    return sendRedirect(event, `/org/${orgMatch.groups.org}` + (query ? '?' + query : ''), 301)
   }
 })

From 36610fe51881c7cbd13971da1890a93f4627650f Mon Sep 17 00:00:00 2001
From: Daniel Roe <daniel@roe.dev>
Date: Fri, 6 Feb 2026 11:16:28 +0000
Subject: [PATCH 16/16] fix: exempt 200.html

---
 server/middleware/canonical-redirects.global.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/server/middleware/canonical-redirects.global.ts b/server/middleware/canonical-redirects.global.ts
index f0e16afea..e35e5aea7 100644
--- a/server/middleware/canonical-redirects.global.ts
+++ b/server/middleware/canonical-redirects.global.ts
@@ -13,6 +13,7 @@
  * - /docs/*         → /package-docs/*
  */
 const pages = [
+  '/200.html',
   '/about',
   '/compare',
   '/org',