refactor: change routing and support 'flat' routes

Author: danielroe

app/components/PackageCard.vue

@@ -23,7 +23,7 @@ function formatDate(dateStr: string): string {
 <template>
   <article class="group card-interactive">
     <NuxtLink
-      :to="`/package/${result.package.name}`"
+      :to="{ name: 'package', params: { package: result.package.name.split('/') } }"
       :prefetch-on="prefetch ? 'visibility' : 'interaction'"
       class="block focus:outline-none decoration-none"
     >
@@ -78,7 +78,7 @@ function formatDate(dateStr: string): string {
     >
       <li v-for="keyword in result.package.keywords.slice(0, 5)" :key="keyword">
         <NuxtLink
-          :to="`/search?q=keywords:${encodeURIComponent(keyword)}`"
+          :to="{ name: 'search', query: { q: `keywords:${keyword}` } }"
           class="tag decoration-none"
         >
           {{ keyword }}

app/components/PackageDependencies.vue

@@ -71,7 +71,7 @@ function truncateVersion(version: string, maxLength = 20): string {
           class="flex items-center justify-between py-1 text-sm gap-2"
         >
           <NuxtLink
-            :to="`/package/${dep}`"
+            :to="{ name: 'package', params: { package: dep.split('/') } }"
             class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate min-w-0"
           >
             {{ dep }}
@@ -111,7 +111,7 @@ function truncateVersion(version: string, maxLength = 20): string {
         >
           <div class="flex items-center gap-2 min-w-0">
             <NuxtLink
-              :to="`/package/${peer.name}`"
+              :to="{ name: 'package', params: { package: peer.name.split('/') } }"
               class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate"
             >
               {{ peer.name }}

app/components/PackageVersions.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { PackumentVersion, PackageVersionInfo } from '#shared/types'
+import type { RouteLocationRaw } from 'vue-router'
 
 const props = defineProps<{
   packageName: string
@@ -56,6 +57,14 @@ function compareVersions(a: string, b: string): number {
   return 0
 }
 
+// Build route object for package version link
+function versionRoute(version: string): RouteLocationRaw {
+  return {
+    name: 'package',
+    params: { package: [...props.packageName.split('/'), 'v', version] },
+  }
+}
+
 // Get prerelease channel or empty string for stable
 function getPrereleaseChannel(version: string): string {
   const parsed = parseVersion(version)
@@ -333,7 +342,7 @@ function formatDate(dateStr: string): string {
           <div class="flex-1 flex items-center justify-between py-1.5 text-sm gap-2 min-w-0">
             <div class="flex items-center gap-2 min-w-0">
               <NuxtLink
-                :to="`/package/${packageName}/v/${row.primaryVersion.version}`"
+                :to="versionRoute(row.primaryVersion.version)"
                 class="font-mono text-fg-muted hover:text-fg transition-colors duration-200 truncate"
               >
                 {{ row.primaryVersion.version }}
@@ -374,7 +383,7 @@ function formatDate(dateStr: string): string {
           >
             <div class="flex items-center gap-2 min-w-0">
               <NuxtLink
-                :to="`/package/${packageName}/v/${v.version}`"
+                :to="versionRoute(v.version)"
                 class="font-mono text-xs text-fg-subtle hover:text-fg-muted transition-colors duration-200 truncate"
               >
                 {{ v.version }}
@@ -452,10 +461,11 @@ function formatDate(dateStr: string): string {
               <div v-else class="flex items-center gap-2 py-1">
                 <span class="w-3" />
                 <NuxtLink
-                  :to="`/package/${packageName}/v/${group.versions[0]?.version}`"
+                  v-if="group.versions[0]"
+                  :to="versionRoute(group.versions[0].version)"
                   class="font-mono text-xs text-fg-muted hover:text-fg transition-colors duration-200"
                 >
-                  {{ group.versions[0]?.version }}
+                  {{ group.versions[0].version }}
                 </NuxtLink>
                 <span
                   v-if="group.versions[0]?.tag"
@@ -474,7 +484,7 @@ function formatDate(dateStr: string): string {
                 >
                   <div class="flex items-center gap-2 min-w-0">
                     <NuxtLink
-                      :to="`/package/${packageName}/v/${v.version}`"
+                      :to="versionRoute(v.version)"
                       class="font-mono text-xs text-fg-subtle hover:text-fg-muted transition-colors duration-200 truncate"
                     >
                       {{ v.version }}

app/middleware/canonical-redirects.global.ts

@@ -0,0 +1,28 @@
+/**
+ * Redirect legacy URLs to canonical paths (client-side only)
+ *
+ * - /package/* → /*
+ * - /package/code/* → /code/*
+ * - /org/* → /@*
+ */
+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/* → /code/*
+  if (path.startsWith('/package/code/')) {
+    return navigateTo(path.replace('/package/code/', '/code/'), { replace: true })
+  }
+
+  // /package/* → /*
+  if (path.startsWith('/package/')) {
+    return navigateTo(path.replace('/package/', '/'), { replace: true })
+  }
+
+  // /org/* → /@*
+  if (path.startsWith('/org/')) {
+    return navigateTo(path.replace('/org/', '/@'), { replace: true })
+  }
+})

app/pages/org/[name].vue app/pages/@[org].vueapp/pages/org/[name].vue renamed to app/pages/@[org].vue

@@ -1,9 +1,14 @@
 <script setup lang="ts">
 import { formatNumber } from '#imports'
 
-const route = useRoute('org-name')
+definePageMeta({
+  name: 'org',
+  alias: ['/org/:org()'],
+})
+
+const route = useRoute('org')
 
-const orgName = computed(() => route.params.name)
+const orgName = computed(() => route.params.org)
 
 const { isConnected } = useConnector()
 
@@ -26,6 +31,13 @@ const packageCount = computed(() => scopedPackages.value.length)
 
 const activeTab = ref<'members' | 'teams'>('members')
 
+// Canonical URL for this org page
+const canonicalUrl = computed(() => `https://npmx.dev/@${orgName.value}`)
+
+useHead({
+  link: [{ rel: 'canonical', href: canonicalUrl }],
+})
+
 useSeoMeta({
   title: () => `@${orgName.value} - npmx`,
   description: () => `npm packages published by the ${orgName.value} organization`,

app/pages/package/[...name].vue app/pages/[...package].vueapp/pages/package/[...name].vue renamed to app/pages/[...package].vue

@@ -2,16 +2,21 @@
 import { joinURL } from 'ufo'
 import type { PackumentVersion, NpmVersionDist } from '#shared/types'
 
-const route = useRoute('package-name')
+definePageMeta({
+  name: 'package',
+  alias: ['/package/:package(.*)*'],
+})
+
+const route = useRoute('package')
 
 // Parse package name and optional version from URL
 // Patterns:
-//   /package/nuxt → packageName: "nuxt", requestedVersion: null
-//   /package/nuxt/v/4.2.0 → packageName: "nuxt", requestedVersion: "4.2.0"
-//   /package/@nuxt/kit → packageName: "@nuxt/kit", requestedVersion: null
-//   /package/@nuxt/kit/v/1.0.0 → packageName: "@nuxt/kit", requestedVersion: "1.0.0"
+//   /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"
 const parsedRoute = computed(() => {
-  const segments = Array.isArray(route.params.name) ? route.params.name : [route.params.name ?? '']
+  const segments = route.params.package || []
 
   // Find the /v/ separator for version
   const vIndex = segments.indexOf('v')
@@ -220,6 +225,16 @@ onMounted(() => {
   nextTick(checkDescriptionOverflow)
 })
 
+// Canonical URL for this package page
+const canonicalUrl = computed(() => {
+  const base = `https://npmx.dev/${packageName.value}`
+  return requestedVersion.value ? `${base}/v/${requestedVersion.value}` : base
+})
+
+useHead({
+  link: [{ rel: 'canonical', href: canonicalUrl }],
+})
+
 useSeoMeta({
   title: () => (pkg.value?.name ? `${pkg.value.name} - npmx` : 'Package - npmx'),
   description: () => pkg.value?.description ?? '',
@@ -246,7 +261,7 @@ defineOgImageComponent('Package', {
             <h1 class="font-mono text-2xl sm:text-3xl font-medium">
               <NuxtLink
                 v-if="orgName"
-                :to="`/org/${orgName}`"
+                :to="{ name: 'org', params: { org: orgName } }"
                 class="text-fg-muted hover:text-fg transition-colors duration-200"
                 >@{{ orgName }}</NuxtLink
               ><span v-if="orgName">/</span
@@ -432,7 +447,10 @@ defineOgImageComponent('Package', {
             </li>
             <li v-if="displayVersion">
               <NuxtLink
-                :to="`/package/code/${pkg.name}/v/${displayVersion.version}`"
+                :to="{
+                  name: 'code',
+                  params: { path: [...pkg.name.split('/'), 'v', displayVersion.version] },
+                }"
                 class="link-subtle font-mono text-sm inline-flex items-center gap-1.5"
               >
                 <span class="i-carbon-code w-4 h-4" />
@@ -560,7 +578,7 @@ defineOgImageComponent('Package', {
             </h2>
             <ul class="flex flex-wrap gap-1.5 list-none m-0 p-0">
               <li v-for="keyword in displayVersion.keywords.slice(0, 15)" :key="keyword">
-                <NuxtLink :to="`/search?q=keywords:${encodeURIComponent(keyword)}`" class="tag">
+                <NuxtLink :to="{ name: 'search', query: { q: `keywords:${keyword}` } }" class="tag">
                   {{ keyword }}
                 </NuxtLink>
               </li>

app/pages/package/code/[...path].vue app/pages/code/[...path].vueapp/pages/package/code/[...path].vue renamed to app/pages/code/[...path].vue

@@ -5,16 +5,21 @@ import type {
   PackageFileContentResponse,
 } from '#shared/types'
 
-const route = useRoute('package-code-path')
+definePageMeta({
+  name: 'code',
+  alias: ['/package/code/:path(.*)*'],
+})
+
+const route = useRoute('code')
 const router = useRouter()
 
 // Parse package name, version, and file path from URL
 // Patterns:
-//   /package/code/nuxt/v/4.2.0 → packageName: "nuxt", version: "4.2.0", filePath: null (show tree)
-//   /package/code/nuxt/v/4.2.0/src/index.ts → packageName: "nuxt", version: "4.2.0", filePath: "src/index.ts"
-//   /package/code/@nuxt/kit/v/1.0.0 → packageName: "@nuxt/kit", version: "1.0.0", filePath: null
+//   /code/nuxt/v/4.2.0 → packageName: "nuxt", version: "4.2.0", filePath: null (show tree)
+//   /code/nuxt/v/4.2.0/src/index.ts → packageName: "nuxt", version: "4.2.0", filePath: "src/index.ts"
+//   /code/@nuxt/kit/v/1.0.0 → packageName: "@nuxt/kit", version: "1.0.0", filePath: null
 const parsedRoute = computed(() => {
-  const segments = Array.isArray(route.params.path) ? route.params.path : [route.params.path ?? '']
+  const segments = route.params.path || []
 
   // Find the /v/ separator for version
   const vIndex = segments.indexOf('v')
@@ -75,8 +80,8 @@ const availableVersions = computed(() => {
 // Version switch handler
 function switchVersion(newVersion: string) {
   const newPath = filePath.value
-    ? `/package/code/${packageName.value}/v/${newVersion}/${filePath.value}`
-    : `/package/code/${packageName.value}/v/${newVersion}`
+    ? `/code/${packageName.value}/v/${newVersion}/${filePath.value}`
+    : `/code/${packageName.value}/v/${newVersion}`
   router.push(newPath)
 }
 
@@ -207,7 +212,7 @@ const breadcrumbs = computed(() => {
 
 // Navigation helper - build URL for a path
 function getCodeUrl(path?: string): string {
-  const base = `/package/code/${packageName.value}/v/${version.value}`
+  const base = `/code/${packageName.value}/v/${version.value}`
   return path ? `${base}/${path}` : base
 }
 
@@ -219,6 +224,15 @@ 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 } }
+}
+
 // Format file size
 function formatBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`
@@ -257,6 +271,19 @@ async function copyPermalink() {
   await navigator.clipboard.writeText(url.toString())
 }
 
+// Canonical URL for this code page
+const canonicalUrl = computed(() => {
+  let url = `https://npmx.dev/code/${packageName.value}/v/${version.value}`
+  if (filePath.value) {
+    url += `/${filePath.value}`
+  }
+  return url
+})
+
+useHead({
+  link: [{ rel: 'canonical', href: canonicalUrl }],
+})
+
 useSeoMeta({
   title: () => {
     if (filePath.value) {
@@ -276,7 +303,7 @@ useSeoMeta({
         <!-- Package info and navigation -->
         <div class="flex items-center gap-2 mb-3 flex-wrap">
           <NuxtLink
-            :to="`/package/${packageName}${version ? `/v/${version}` : ''}`"
+            :to="packageRoute(version)"
             class="font-mono text-lg font-medium hover:text-fg transition-colors"
           >
             <span v-if="orgName" class="text-fg-muted">@{{ orgName }}/</span
@@ -337,7 +364,7 @@ useSeoMeta({
     <!-- Error: no version -->
     <div v-if="!version" class="container py-20 text-center">
       <p class="text-fg-muted mb-4">Version is required to browse code</p>
-      <NuxtLink :to="`/package/${packageName}`" class="btn"> Go to package </NuxtLink>
+      <NuxtLink :to="packageRoute()" class="btn"> Go to package </NuxtLink>
     </div>
 
     <!-- Loading state -->
@@ -349,9 +376,7 @@ useSeoMeta({
     <!-- Error state -->
     <div v-else-if="treeStatus === 'error'" class="container py-20 text-center" role="alert">
       <p class="text-fg-muted mb-4">Failed to load files for this package version</p>
-      <NuxtLink :to="`/package/${packageName}${version ? `/v/${version}` : ''}`" class="btn">
-        Back to package
-      </NuxtLink>
+      <NuxtLink :to="packageRoute(version)" class="btn"> Back to package </NuxtLink>
     </div>
 
     <!-- Main content: file tree + file viewer -->

app/pages/index.vue

@@ -98,7 +98,7 @@ defineOgImageComponent('Default')
           :key="pkg"
         >
           <NuxtLink
-            :to="`/package/${pkg}`"
+            :to="{ name: 'package', params: { package: [pkg] } }"
             class="link-subtle font-mono text-sm inline-flex items-center gap-2 group"
           >
             <span

server/utils/code-highlight.ts

@@ -184,10 +184,10 @@ function linkifyImports(html: string, options?: LinkifyOptions): string {
     const dep = dependencies?.[packageName]
     if (dep) {
       // Link to code browser with resolved version
-      return `/package/code/${packageName}/v/${dep.version}`
+      return `/code/${packageName}/v/${dep.version}`
     }
     // Fall back to package page if not a known dependency
-    return `/package/${packageName}`
+    return `/${packageName}`
   }
 
   // Match: from keyword span followed by string span containing module specifier

server/utils/import-resolver.ts

@@ -212,7 +212,7 @@ export function createImportResolver(
   return (specifier: string) => {
     const resolved = resolveRelativeImport(specifier, currentFile, files)
     if (resolved) {
-      return `/package/code/${packageName}/v/${version}/${resolved.path}`
+      return `/code/${packageName}/v/${version}/${resolved.path}`
     }
     return null
   }