feat: new routing schema (#674)

Co-authored-by: Daniel Roe <daniel@roe.dev>

Author: mikouaji

.lighthouserc.cjs

@@ -29,7 +29,7 @@ module.exports = {
       url: [
         'http://localhost:3000/',
         'http://localhost:3000/search?q=nuxt',
-        'http://localhost:3000/nuxt',
+        'http://localhost:3000/package/nuxt',
       ],
       numberOfRuns: 1,
       chromePath: findChrome(),

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="`/${pkg}`"
+                :to="`/package/${pkg}`"
                 class="block px-3 py-2 font-mono text-sm text-fg hover:bg-bg-subtle transition-colors truncate"
               >
                 {{ pkg }}

app/components/Package/MetricsBadges.vue

@@ -45,7 +45,7 @@ const typesTooltip = computed(() => {
 const typesHref = computed(() => {
   if (!analysis.value) return null
   if (analysis.value.types?.kind === '@types') {
-    return `/${analysis.value.types.packageName}`
+    return `/package/${analysis.value.types.packageName}`
   }
   return null
 })

app/components/Package/SkillsModal.vue

@@ -8,7 +8,7 @@ const props = defineProps<{
 }>()
 
 function getSkillSourceUrl(skill: SkillListItem): string {
-  const base = `/code/${props.packageName}`
+  const base = `/package-code/${props.packageName}`
   const versionPath = props.version ? `/v/${props.version}` : ''
   return `${base}${versionPath}/skills/${skill.dirName}/SKILL.md`
 }
@@ -101,7 +101,7 @@ function getWarningTooltip(skill: SkillListItem): string | undefined {
         </template>
       </i18n-t>
       <a
-        href="/skills-npm"
+        href="/package/skills-npm"
         class="inline-flex items-center gap-1 text-xs text-fg-subtle hover:text-fg transition-colors shrink-0"
       >
         {{ $t('package.skills.learn_more') }}

app/components/Terminal/Install.vue

@@ -149,7 +149,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               ></code
             >
             <NuxtLink
-              :to="`/${typesPackageName}`"
+              :to="`/package/${typesPackageName}`"
               class="text-fg-subtle hover:text-fg-muted text-xs transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50 rounded"
               :title="$t('package.get_started.view_types', { package: typesPackageName })"
             >
@@ -228,7 +228,7 @@ const copyCreateCommand = () => copyCreate(getFullCreateCommand())
               }}</span>
             </button>
             <NuxtLink
-              :to="`/${createPackageInfo.packageName}`"
+              :to="`/package/${createPackageInfo.packageName}`"
               class="text-fg-subtle hover:text-fg-muted text-xs transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fg/50 rounded"
               :title="`View ${createPackageInfo.packageName}`"
             >

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="`/${packageName}`"
+            :to="`/package/${packageName}`"
             class="text-xs text-fg-subtle hover:text-fg transition-[color] focus-visible:outline-none focus-visible:text-fg"
             @click="isOpen = false"
           >

app/components/compare/PackageSelector.vue

@@ -64,7 +64,7 @@ function handleBlur() {
         class="inline-flex items-center gap-2 px-3 py-1.5 bg-bg-subtle border border-border rounded-md"
       >
         <NuxtLink
-          :to="`/${pkg}`"
+          :to="`/package/${pkg}`"
           class="font-mono text-sm text-fg hover:text-accent transition-colors"
         >
           {{ pkg }}

app/middleware/canonical-redirects.global.ts

@@ -1,28 +1,49 @@
 /**
  * Redirect legacy URLs to canonical paths (client-side only)
  *
- * - /package/* → /*
- * - /package/code/* → /code/*
+ * - /package/code/* → /package-code/*
+ * - /code/* → /package-code/*
+ * - /package/docs/* → /package-docs/*
+ * - /docs/* → /package-docs/*
  * - /org/* → /@*
+ * - /* → /package/* (Unless its 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/* → /code/*
+  // /package/code/* → /package-code/*
   if (path.startsWith('/package/code/')) {
-    return navigateTo(path.replace('/package/code/', '/code/'), { replace: true })
+    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/* → /*
-  if (path.startsWith('/package/')) {
-    return navigateTo(path.replace('/package/', '/'), { 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 its an existing page)
+  if (path.startsWith('/') && !path.startsWith('/package/')) {
+    const router = useRouter()
+    const resolved = router.resolve(path)
+    if (resolved?.matched?.length === 1 && resolved.matched[0]?.path === '/:package(.*)*') {
+      return navigateTo(`/package${path}`, { replace: true })
+    }
+  }
 })

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

@@ -8,7 +8,8 @@ import { formatBytes } from '~/utils/formatters'
 
 definePageMeta({
   name: 'code',
-  alias: ['/package/code/:path(.*)*'],
+  path: '/package-code/:path+',
+  alias: ['/package/code/:path+', '/code/:path+'],
 })
 
 const route = useRoute('code')
@@ -19,7 +20,7 @@ const route = useRoute('code')
 //   /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 = route.params.path || []
+  const segments = route.params.path
 
   // Find the /v/ separator for version
   const vIndex = segments.indexOf('v')
@@ -50,7 +51,7 @@ const { data: pkg } = usePackage(packageName)
 
 // URL pattern for version selector - includes file path if present
 const versionUrlPattern = computed(() => {
-  const base = `/code/${packageName.value}/v/{version}`
+  const base = `/package-code/${packageName.value}/v/{version}`
   return filePath.value ? `${base}/${filePath.value}` : base
 })
 
@@ -193,7 +194,7 @@ const breadcrumbs = computed(() => {
 
 // Navigation helper - build URL for a path
 function getCodeUrl(path?: string): string {
-  const base = `/code/${packageName.value}/v/${version.value}`
+  const base = `/package-code/${packageName.value}/v/${version.value}`
   return path ? `${base}/${path}` : base
 }
 
@@ -248,7 +249,7 @@ function copyPermalinkUrl() {
 
 // Canonical URL for this code page
 const canonicalUrl = computed(() => {
-  let url = `https://npmx.dev/code/${packageName.value}/v/${version.value}`
+  let url = `https://npmx.dev/package-code/${packageName.value}/v/${version.value}`
   if (filePath.value) {
     url += `/${filePath.value}`
   }

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

@@ -5,13 +5,15 @@ import { assertValidPackageName, fetchLatestVersion } from '#shared/utils/npm'
 
 definePageMeta({
   name: 'docs',
+  path: '/package-docs/:path+',
+  alias: ['/package/docs/:path+', '/docs/:path+'],
 })
 
 const route = useRoute('docs')
 const router = useRouter()
 
 const parsedRoute = computed(() => {
-  const segments = route.params.path?.filter(Boolean) || []
+  const segments = route.params.path?.filter(Boolean)
   const vIndex = segments.indexOf('v')
 
   if (vIndex === -1 || vIndex >= segments.length - 1) {
@@ -45,7 +47,7 @@ if (import.meta.server && !requestedVersion.value && packageName.value) {
   if (version) {
     setResponseHeader(useRequestEvent()!, 'Cache-Control', 'no-cache')
     app.runWithContext(() =>
-      navigateTo('/docs/' + packageName.value + '/v/' + version, { redirectCode: 302 }),
+      navigateTo('/package-docs/' + packageName.value + '/v/' + version, { redirectCode: 302 }),
     )
   }
 }
@@ -54,7 +56,7 @@ watch(
   [requestedVersion, latestVersion, packageName],
   ([version, latest, name]) => {
     if (!version && latest && name) {
-      router.replace(`/docs/${name}/v/${latest}`)
+      router.replace(`/package-docs/${name}/v/${latest}`)
     }
   },
   { immediate: true },
@@ -120,7 +122,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
           <div class="flex items-center gap-3 min-w-0">
             <NuxtLink
               v-if="packageName"
-              :to="`/${packageName}`"
+              :to="{ name: 'package', params: { package: [packageName] } }"
               class="font-mono text-lg sm:text-xl font-semibold text-fg hover:text-fg-muted transition-colors truncate"
             >
               {{ packageName }}
@@ -131,7 +133,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
               :current-version="resolvedVersion"
               :versions="pkg.versions"
               :dist-tags="pkg['dist-tags']"
-              :url-pattern="`/docs/${packageName}/v/{version}`"
+              :url-pattern="`/package-docs/${packageName}/v/{version}`"
             />
             <span v-else-if="resolvedVersion" class="text-fg-subtle font-mono text-sm shrink-0">
               {{ resolvedVersion }}
@@ -179,7 +181,7 @@ const showEmptyState = computed(() => docsData.value?.status !== 'ok')
             <div class="flex gap-4 mt-4">
               <NuxtLink
                 v-if="packageName"
-                :to="`/${packageName}`"
+                :to="{ name: 'package', params: { package: [packageName] } }"
                 class="link-subtle font-mono text-sm"
               >
                 View package