refactor: use /raw/ server route instead of middleware for markdown

Address review feedback from @atinux:
- Replace middleware with server route at /raw/[...slug].md
- Update vercel.json rewrites to point to /raw/:path.md
- Add curl user-agent rewrite support for CLI tools
- Enable CDN-level caching for markdown responses

Also fix maintainer URLs to use npmx.dev instead of npmjs.com

Author: BYK

nuxt.config.ts

@@ -77,7 +77,7 @@ export default defineNuxtConfig({
     '/': { prerender: true },
     '/opensearch.xml': { isr: true },
     '/**': { isr: 60 },
-    '/*.md': { isr: 60 },
+    '/raw/**': { isr: 60 },
     '/package/**': { isr: 60 },
     '/search': { isr: false, cache: false },
     // infinite cache (versioned - doesn't change)

server/middleware/markdown.ts server/routes/raw/[...slug].md.get.tsserver/middleware/markdown.ts renamed to server/routes/raw/[...slug].md.get.ts

@@ -1,4 +1,4 @@
-import { generatePackageMarkdown } from '../utils/markdown'
+import { generatePackageMarkdown } from '../../utils/markdown'
 import * as v from 'valibot'
 import { PackageRouteParamsSchema } from '#shared/schemas/package'
 import {
@@ -92,11 +92,11 @@ function isStandardReadme(filename: string | undefined): boolean {
   return !!filename && standardReadmePattern.test(filename)
 }
 
-function parsePackageParamsFromPath(path: string): {
+function parsePackageParamsFromSlug(slug: string): {
   rawPackageName: string
   rawVersion: string | undefined
 } {
-  const segments = path.slice(1).split('/').filter(Boolean)
+  const segments = slug.split('/').filter(Boolean)
 
   if (segments.length === 0) {
     return { rawPackageName: '', rawVersion: undefined }
@@ -127,8 +127,22 @@ function parsePackageParamsFromPath(path: string): {
   }
 }
 
-async function handleMarkdownRequest(packagePath: string): Promise<string> {
-  const { rawPackageName, rawVersion } = parsePackageParamsFromPath(packagePath)
+export default defineEventHandler(async event => {
+  // Get the slug parameter - Nitro captures it as "slug.md" due to the route pattern
+  const params = getRouterParams(event)
+  const slugParam = params['slug.md'] || params.slug
+
+  if (!slugParam) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: 'Package not found',
+    })
+  }
+
+  // Remove .md suffix if present (it will be there from the route)
+  const slug = slugParam.endsWith('.md') ? slugParam.slice(0, -3) : slugParam
+
+  const { rawPackageName, rawVersion } = parsePackageParamsFromSlug(slug)
 
   if (!rawPackageName) {
     throw createError({
@@ -142,7 +156,15 @@ async function handleMarkdownRequest(packagePath: string): Promise<string> {
     version: rawVersion,
   })
 
-  const packageData = await fetchNpmPackage(packageName)
+  let packageData
+  try {
+    packageData = await fetchNpmPackage(packageName)
+  } catch {
+    throw createError({
+      statusCode: 502,
+      statusMessage: ERROR_NPM_FETCH_FAILED,
+    })
+  }
 
   let targetVersion = version
   if (!targetVersion) {
@@ -193,63 +215,21 @@ async function handleMarkdownRequest(packagePath: string): Promise<string> {
 
   const repoInfo = parseRepositoryInfo(packageData.repository)
 
-  return generatePackageMarkdown({
+  const markdown = generatePackageMarkdown({
     pkg: packageData,
     version: versionData,
     readme: readmeContent && readmeContent !== NPM_MISSING_README_SENTINEL ? readmeContent : null,
     weeklyDownloads: weeklyDownloadsData?.downloads,
     dailyDownloads: dailyDownloads ?? undefined,
     repoInfo,
   })
-}
 
-/** Handle .md suffix and Accept: text/markdown header requests */
-export default defineEventHandler(async event => {
-  const url = getRequestURL(event)
-  const path = url.pathname
+  setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
+  setHeader(
+    event,
+    'Cache-Control',
+    `public, max-age=${CACHE_MAX_AGE_ONE_HOUR}, stale-while-revalidate`,
+  )
 
-  if (
-    path.startsWith('/api/') ||
-    path.startsWith('/_') ||
-    path.startsWith('/__') ||
-    path === '/search' ||
-    path.startsWith('/search') ||
-    path.startsWith('/code/') ||
-    path === '/' ||
-    path === '/.md'
-  ) {
-    return
-  }
-
-  const isMarkdownPath = path.endsWith('.md') && path.length > 3
-  const acceptHeader = getHeader(event, 'accept') ?? ''
-  const wantsMarkdown = acceptHeader.includes('text/markdown')
-
-  if (!isMarkdownPath && !wantsMarkdown) {
-    return
-  }
-
-  const packagePath = isMarkdownPath ? path.slice(0, -3) : path
-
-  try {
-    const markdown = await handleMarkdownRequest(packagePath)
-
-    setHeader(event, 'Content-Type', 'text/markdown; charset=utf-8')
-    setHeader(
-      event,
-      'Cache-Control',
-      `public, max-age=${CACHE_MAX_AGE_ONE_HOUR}, stale-while-revalidate`,
-    )
-
-    return markdown
-  } catch (error: unknown) {
-    if (error && typeof error === 'object' && 'statusCode' in error) {
-      throw error
-    }
-
-    throw createError({
-      statusCode: 502,
-      statusMessage: ERROR_NPM_FETCH_FAILED,
-    })
-  }
+  return markdown
 })

server/utils/markdown.ts

@@ -251,7 +251,7 @@ export function generatePackageMarkdown(options: PackageMarkdownOptions): string
       const username = (maintainer as { username?: string }).username
       const name = maintainer.name || username || 'Unknown'
       if (username) {
-        lines.push(`- [${name}](https://www.npmjs.com/~${username})`)
+        lines.push(`- [${name}](https://npmx.dev/~${username})`)
       } else {
         lines.push(`- ${name}`)
       }

vercel.json

@@ -2,9 +2,14 @@
   "$schema": "https://openapi.vercel.sh/vercel.json",
   "rewrites": [
     {
-      "source": "/:path((?!api|_nuxt|_v|__nuxt|search|code|\\.md$).*)",
+      "source": "/:path((?!api|_nuxt|_v|__nuxt|search|code|raw/).*)",
       "has": [{ "type": "header", "key": "accept", "value": "(.*?)text/markdown(.*)" }],
-      "destination": "/:path.md"
+      "destination": "/raw/:path.md"
+    },
+    {
+      "source": "/:path((?!api|_nuxt|_v|__nuxt|search|code|raw/).*)",
+      "has": [{ "type": "header", "key": "user-agent", "value": "curl/.*" }],
+      "destination": "/raw/:path.md"
     }
   ],
   "redirects": [