feat: add per-entrypoint API docs pages for multi-export packages

Packages with only subpath exports (no root export) previously got no
docs because esm.sh returns 404 for their root URL. Fix by falling back
to the npm registry  field to discover typed subpath entries.

Additionally, multi-entrypoint packages now get separate docs pages per
subpath with an EntrypointSelector dropdown, instead of dumping all
symbols into one flat page. The base URL redirects to the first
entrypoint.

URL structure: /package-docs/{pkg}/v/{version}/{entrypoint}

Closes #1479

Author: serhalp

app/components/EntrypointSelector.vue

@@ -0,0 +1,30 @@
+<script setup lang="ts">
+const props = defineProps<{
+  packageName: string
+  version: string
+  currentEntrypoint: string
+  entrypoints: string[]
+}>()
+
+function getEntrypointLabel(entrypoint: string): string {
+  return entrypoint === '.' ? '.' : `./${entrypoint}`
+}
+
+function onSelect(event: Event) {
+  const target = event.target as HTMLSelectElement
+  navigateTo(docsRoute(props.packageName, props.version, target.value))
+}
+</script>
+
+<template>
+  <select
+    :value="currentEntrypoint"
+    :aria-label="$t('package.docs.select_entrypoint')"
+    class="text-fg-subtle font-mono text-sm bg-transparent border border-border rounded px-2 py-1 hover:text-fg hover:border-border-subtle transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring shrink-0"
+    @change="onSelect"
+  >
+    <option v-for="ep in entrypoints" :key="ep" :value="ep">
+      {{ getEntrypointLabel(ep) }}
+    </option>
+  </select>
+</template>

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

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { setResponseHeader } from 'h3'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
 
 definePageMeta({
   name: 'docs',
@@ -13,24 +14,19 @@ const router = useRouter()
 const { t } = useI18n()
 
 const parsedRoute = computed(() => {
-  const segments = route.params.path?.filter(Boolean)
-  const vIndex = segments.indexOf('v')
-
-  if (vIndex === -1 || vIndex >= segments.length - 1) {
-    return {
-      packageName: segments.join('/'),
-      version: null as string | null,
-    }
-  }
+  const rawPath = route.params.path?.filter(Boolean).join('/') ?? ''
+  const { packageName, version, rest } = parsePackageParam(rawPath)
 
   return {
-    packageName: segments.slice(0, vIndex).join('/'),
-    version: segments.slice(vIndex + 1).join('/'),
+    packageName,
+    version: version ?? null,
+    entrypoint: rest.length > 0 ? rest.join('/') : null,
   }
 })
 
 const packageName = computed(() => parsedRoute.value.packageName)
 const requestedVersion = computed(() => parsedRoute.value.version)
+const entrypoint = computed(() => parsedRoute.value.entrypoint)
 
 // Validate package name on server-side for early error detection
 if (import.meta.server && packageName.value) {
@@ -48,12 +44,8 @@ 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(
-        { name: 'docs', params: { path: pathSegments as [string, ...string[]] } },
-        { redirectCode: 302 },
-      ),
+      navigateTo(docsRoute(packageName.value, version), { redirectCode: 302 }),
     )
   }
 }
@@ -62,8 +54,7 @@ watch(
   [requestedVersion, latestVersion, packageName],
   ([version, latest, name]) => {
     if (!version && latest && name) {
-      const pathSegments = [...name.split('/'), 'v', latest]
-      router.replace({ name: 'docs', params: { path: pathSegments as [string, ...string[]] } })
+      router.replace(docsRoute(name, latest))
     }
   },
   { immediate: true },
@@ -90,7 +81,8 @@ useCommandPalettePackageCommands(commandPalettePackageContext)
 
 const docsUrl = computed(() => {
   if (!packageName.value || !resolvedVersion.value) return null
-  return `/api/registry/docs/${packageName.value}/v/${resolvedVersion.value}`
+  const base = `/api/registry/docs/${packageName.value}/v/${resolvedVersion.value}`
+  return entrypoint.value ? `${base}/${entrypoint.value}` : base
 })
 
 const shouldFetch = computed(() => !!docsUrl.value)
@@ -119,9 +111,10 @@ const latestVersionDetailed = computed(() => {
   return pkg.value.versions[latestTag] ?? null
 })
 
-const versionUrlPattern = computed(
-  () => `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`,
-)
+const versionUrlPattern = computed(() => {
+  const base = `/package-docs/${pkg.value?.name || packageName.value}/v/{version}`
+  return entrypoint.value && entrypoint.value !== '.' ? `${base}/${entrypoint.value}` : base
+})
 
 useCommandPaletteVersionCommands(commandPalettePackageContext, versionUrlPattern)
 
@@ -171,6 +164,26 @@ const stickyStyle = computed(() => {
     '--combined-header-height': `${56 + (packageHeaderHeight.value || 44)}px`,
   }
 })
+
+// Multi-entrypoint support
+const entrypoints = computed(() => docsData.value?.entrypoints ?? null)
+const hasRootEntrypoint = computed(() => entrypoints.value?.includes('.') ?? false)
+const currentEntrypoint = computed(
+  () => docsData.value?.entrypoint ?? entrypoint.value ?? (hasRootEntrypoint.value ? '.' : ''),
+)
+
+// Redirect to first entrypoint for multi-entrypoint packages
+watch(docsData, data => {
+  if (
+    data?.entrypoints?.length &&
+    !data.entrypoints.includes('.') &&
+    !entrypoint.value &&
+    resolvedVersion.value
+  ) {
+    const firstEntrypoint = data.entrypoints[0]!
+    router.replace(docsRoute(packageName.value, resolvedVersion.value, firstEntrypoint))
+  }
+})
 </script>
 
 <template>
@@ -184,6 +197,18 @@ const stickyStyle = computed(() => {
       page="docs"
     />
 
+    <div
+      v-if="entrypoints && currentEntrypoint && resolvedVersion"
+      class="container py-2 border-b border-border"
+    >
+      <EntrypointSelector
+        :package-name="packageName"
+        :version="resolvedVersion"
+        :current-entrypoint="currentEntrypoint"
+        :entrypoints="entrypoints"
+      />
+    </div>
+
     <div class="flex" dir="ltr">
       <!-- Sidebar TOC -->
       <aside

app/utils/router.ts

@@ -52,3 +52,22 @@ export function diffRoute(
     },
   }
 }
+
+export function docsRoute(
+  packageName: string,
+  version: string,
+  entrypoint?: string | null,
+): RouteLocationRaw {
+  const pathSegments = [...packageName.split('/'), 'v', version]
+
+  if (entrypoint && entrypoint !== '.') {
+    pathSegments.push(...entrypoint.split('/'))
+  }
+
+  return {
+    name: 'docs',
+    params: {
+      path: pathSegments as [string, ...string[]],
+    },
+  }
+}

i18n/locales/en.json

@@ -462,7 +462,8 @@
       "page_title_name": "{name} docs - npmx",
       "page_title_version": "{name} docs - npmx",
       "og_title": "{name} - Docs",
-      "view_package": "View package"
+      "view_package": "View package",
+      "select_entrypoint": "Select entrypoint"
     },
     "get_started": {
       "title": "Get started",

i18n/locales/fr-FR.json

@@ -450,7 +450,8 @@
       "page_title_name": "Documentation {name} - npmx",
       "page_title_version": "Documentation {name} - npmx",
       "og_title": "{name} - Documentation",
-      "view_package": "Voir le paquet"
+      "view_package": "Voir le paquet",
+      "select_entrypoint": "Sélectionner le point d'entrée"
     },
     "get_started": {
       "title": "Commencer",

i18n/schema.json

@@ -1392,6 +1392,9 @@
             },
             "view_package": {
               "type": "string"
+            },
+            "select_entrypoint": {
+              "type": "string"
             }
           },
           "additionalProperties": false

server/api/registry/docs/[...pkg].get.ts

@@ -1,3 +1,8 @@
+import type { DocsResponse } from '#shared/types'
+import { assertValidPackageName } from '#shared/utils/npm'
+import { parsePackageParam } from '#shared/utils/parse-package-param'
+import { generateDocsWithDeno, getEntrypoints } from '#server/utils/docs'
+
 export default defineCachedEventHandler(
   async event => {
     const pkgParam = getRouterParam(event, 'pkg')
@@ -6,7 +11,7 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package name is required' })
     }
 
-    const { packageName, version } = parsePackageParam(pkgParam)
+    const { packageName, version, rest } = parsePackageParam(pkgParam)
 
     if (!packageName) {
       // TODO: throwing 404 rather than 400 as it's cacheable
@@ -19,9 +24,34 @@ export default defineCachedEventHandler(
       throw createError({ statusCode: 404, message: 'Package version is required' })
     }
 
+    // Extract entrypoint from remaining path segments (e.g., ["router.js"] -> "router.js")
+    const entrypoint = rest.length > 0 ? rest.join('/') : undefined
+
+    // Discover available entrypoints (null for single-entrypoint packages)
+    const entrypoints = await getEntrypoints(packageName, version)
+    const hasRootEntrypoint = entrypoints?.includes('.') ?? false
+    const requestedEntrypoint = entrypoint === '.' ? undefined : entrypoint
+    const currentEntrypoint =
+      requestedEntrypoint ?? (entrypoints && hasRootEntrypoint ? '.' : undefined)
+    const entrypointFields = entrypoints ? { entrypoints, entrypoint: currentEntrypoint } : {}
+
+    // If the package only has subpath entrypoints, return the list so the
+    // client can redirect to the first concrete entrypoint page.
+    if (entrypoints && !hasRootEntrypoint && !requestedEntrypoint) {
+      return {
+        package: packageName,
+        version,
+        html: '',
+        toc: null,
+        status: 'ok',
+        entrypoints,
+        entrypoint: entrypoints[0],
+      } satisfies DocsResponse
+    }
+
     let generated
     try {
-      generated = await generateDocsWithDeno(packageName, version)
+      generated = await generateDocsWithDeno(packageName, version, requestedEntrypoint)
     } catch (error) {
       // eslint-disable-next-line no-console
       console.error(`Doc generation failed for ${packageName}@${version}:`, error)
@@ -32,6 +62,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'error',
         message: 'Failed to generate documentation. Please try again later.',
+        ...entrypointFields,
       } satisfies DocsResponse
     }
 
@@ -43,6 +74,7 @@ export default defineCachedEventHandler(
         toc: null,
         status: 'missing',
         message: 'Docs are not available for this package. It may not have TypeScript types.',
+        ...entrypointFields,
       } satisfies DocsResponse
     }
 
@@ -52,14 +84,15 @@ export default defineCachedEventHandler(
       html: generated.html,
       toc: generated.toc,
       status: 'ok',
+      ...entrypointFields,
     } satisfies DocsResponse
   },
   {
     maxAge: 60 * 60, // 1 hour cache
     swr: true,
     getKey: event => {
       const pkg = getRouterParam(event, 'pkg') ?? ''
-      return `docs:v2:${pkg}`
+      return `docs:v3:${pkg}`
     },
   },
 )