feat: unifying npm registry requests with caching

.gitignore

@@ -40,5 +40,7 @@ test-results/
 # generated files
 shared/types/lexicons
 
+**/__screenshots__/**
+
 # output
 .vercel

app/composables/npm/useNpmSearch.ts

@@ -5,7 +5,6 @@ import type {
   NpmDownloadCount,
   MinimalPackument,
 } from '#shared/types'
-import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
 
 /**
  * Convert packument to search result format for display
@@ -55,7 +54,8 @@ export function useNpmSearch(
   query: MaybeRefOrGetter<string>,
   options: MaybeRefOrGetter<NpmSearchOptions> = {},
 ) {
-  const cachedFetch = useCachedFetch()
+  const { $npmRegistry } = useNuxtApp()
+
   // Client-side cache
   const cache = shallowRef<{
     query: string
@@ -70,7 +70,7 @@ export function useNpmSearch(
 
   const asyncData = useLazyAsyncData(
     () => `search:incremental:${toValue(query)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry, $npmApi }, { signal }) => {
       const q = toValue(query)
 
       if (!q.trim()) {
@@ -91,8 +91,8 @@ export function useNpmSearch(
       if (q.length === 1) {
         const encodedName = encodePackageName(q)
         const [{ data: pkg, isStale }, { data: downloads }] = await Promise.all([
-          cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, { signal }),
-          cachedFetch<NpmDownloadCount>(`${NPM_API}/downloads/point/last-week/${encodedName}`, {
+          $npmRegistry<Packument>(`/${encodedName}`, { signal }),
+          $npmApi<NpmDownloadCount>(`/downloads/point/last-week/${encodedName}`, {
             signal,
           }),
         ])
@@ -122,8 +122,8 @@ export function useNpmSearch(
         }
       }
 
-      const { data: response, isStale } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+      const { data: response, isStale } = await $npmRegistry<NpmSearchResponse>(
+        `/-/v1/search?${params.toString()}`,
         { signal },
         60,
       )
@@ -179,8 +179,8 @@ export function useNpmSearch(
       params.set('size', String(size))
       params.set('from', String(from))
 
-      const { data: response } = await cachedFetch<NpmSearchResponse>(
-        `${NPM_REGISTRY}/-/v1/search?${params.toString()}`,
+      const { data: response } = await $npmRegistry<NpmSearchResponse>(
+        `/-/v1/search?${params.toString()}`,
         {},
         60,
       )

app/composables/npm/useOrgPackages.ts

@@ -1,6 +1,6 @@
+import type { NuxtApp } from '#app'
 import type { NpmSearchResponse, NpmSearchResult, MinimalPackument } from '#shared/types'
 import { emptySearchResponse, packumentToSearchResult } from './useNpmSearch'
-import { NPM_REGISTRY, NPM_API } from '~/utils/npm/common'
 import { mapWithConcurrency } from '#shared/utils/async'
 
 /**
@@ -10,6 +10,7 @@ import { mapWithConcurrency } from '#shared/utils/async'
  * Note: npm bulk downloads API does not support scoped packages.
  */
 async function fetchBulkDownloads(
+  $npmApi: NuxtApp['$npmApi'],
   packageNames: string[],
   options: Parameters<typeof $fetch>[1] = {},
 ): Promise<Map<string, number>> {
@@ -28,11 +29,11 @@ async function fetchBulkDownloads(
     bulkPromises.push(
       (async () => {
         try {
-          const response = await $fetch<Record<string, { downloads: number } | null>>(
-            `${NPM_API}/downloads/point/last-week/${chunk.join(',')}`,
+          const response = await $npmApi<Record<string, { downloads: number } | null>>(
+            `/downloads/point/last-week/${chunk.join(',')}`,
             options,
           )
-          for (const [name, data] of Object.entries(response)) {
+          for (const [name, data] of Object.entries(response.data)) {
             if (data?.downloads !== undefined) {
               downloads.set(name, data.downloads)
             }
@@ -54,8 +55,8 @@ async function fetchBulkDownloads(
         const results = await Promise.allSettled(
           batch.map(async name => {
             const encoded = encodePackageName(name)
-            const data = await $fetch<{ downloads: number }>(
-              `${NPM_API}/downloads/point/last-week/${encoded}`,
+            const { data } = await $npmApi<{ downloads: number }>(
+              `/downloads/point/last-week/${encoded}`,
             )
             return { name, downloads: data.downloads }
           }),
@@ -80,11 +81,9 @@ async function fetchBulkDownloads(
  * Returns search-result-like objects for compatibility with PackageList
  */
 export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `org-packages:${toValue(orgName)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry, $npmApi }, { signal }) => {
       const org = toValue(orgName)
       if (!org) {
         return emptySearchResponse
@@ -93,8 +92,8 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
       // Get all package names in the org
       let packageNames: string[]
       try {
-        const { data } = await cachedFetch<Record<string, string>>(
-          `${NPM_REGISTRY}/-/org/${encodeURIComponent(org)}/package`,
+        const { data } = await $npmRegistry<Record<string, string>>(
+          `/-/org/${encodeURIComponent(org)}/package`,
           { signal },
         )
         packageNames = Object.keys(data)
@@ -124,10 +123,9 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
             async name => {
               try {
                 const encoded = encodePackageName(name)
-                const { data: pkg } = await cachedFetch<MinimalPackument>(
-                  `${NPM_REGISTRY}/${encoded}`,
-                  { signal },
-                )
+                const { data: pkg } = await $npmRegistry<MinimalPackument>(`/${encoded}`, {
+                  signal,
+                })
                 return pkg
               } catch {
                 return null
@@ -141,7 +139,7 @@ export function useOrgPackages(orgName: MaybeRefOrGetter<string>) {
           )
         })(),
         // Fetch downloads in bulk
-        fetchBulkDownloads(packageNames, { signal }),
+        fetchBulkDownloads($npmApi, packageNames, { signal }),
       ])
 
       // Convert to search results with download data

app/composables/npm/useOutdatedDependencies.ts

@@ -1,3 +1,4 @@
+import type { NuxtApp } from '#app'
 import { maxSatisfying, prerelease, major, minor, diff, gt } from 'semver'
 import type { Packument } from '#shared/types'
 import { mapWithConcurrency } from '#shared/utils/async'
@@ -7,7 +8,6 @@ import {
   isNonSemverConstraint,
   constraintIncludesPrerelease,
 } from '~/utils/npm/outdated-dependencies'
-import { NPM_REGISTRY } from '~/utils/npm/common'
 
 // Cache for packument fetches to avoid duplicate requests across components
 const packumentCache = new Map<string, Promise<Packument | null>>()
@@ -18,6 +18,7 @@ const packumentCache = new Map<string, Promise<Packument | null>>()
  */
 async function checkDependencyOutdated(
   cachedFetch: CachedFetchFunction,
+  $npmRegistry: NuxtApp['$npmRegistry'],
   packageName: string,
   constraint: string,
 ): Promise<OutdatedDependencyInfo | null> {
@@ -31,7 +32,7 @@ async function checkDependencyOutdated(
   if (cached) {
     packument = await cached
   } else {
-    const promise = cachedFetch<Packument>(`${NPM_REGISTRY}/${encodePackageName(packageName)}`)
+    const promise = $npmRegistry<Packument>(`/${encodePackageName(packageName)}`)
       .then(({ data }) => data)
       .catch(() => null)
     packumentCache.set(packageName, promise)
@@ -92,6 +93,7 @@ async function checkDependencyOutdated(
 export function useOutdatedDependencies(
   dependencies: MaybeRefOrGetter<Record<string, string> | undefined>,
 ) {
+  const { $npmRegistry } = useNuxtApp()
   const cachedFetch = useCachedFetch()
   const outdated = shallowRef<Record<string, OutdatedDependencyInfo>>({})
 
@@ -105,7 +107,7 @@ export function useOutdatedDependencies(
     const batchResults = await mapWithConcurrency(
       entries,
       async ([name, constraint]) => {
-        const info = await checkDependencyOutdated(cachedFetch, name, constraint)
+        const info = await checkDependencyOutdated(cachedFetch, $npmRegistry, name, constraint)
         return [name, info] as const
       },
       5,

app/composables/npm/usePackage.ts

@@ -1,5 +1,4 @@
 import type { Packument, SlimPackument, SlimVersion, SlimPackumentVersion } from '#shared/types'
-import { NPM_REGISTRY } from '~/utils/npm/common'
 import { extractInstallScriptsInfo } from '~/utils/install-scripts'
 
 /** Number of recent versions to include in initial payload */
@@ -98,13 +97,11 @@ export function usePackage(
   name: MaybeRefOrGetter<string>,
   requestedVersion?: MaybeRefOrGetter<string | null>,
 ) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `package:${toValue(name)}:${toValue(requestedVersion) ?? ''}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmRegistry }, { signal }) => {
       const encodedName = encodePackageName(toValue(name))
-      const { data: r, isStale } = await cachedFetch<Packument>(`${NPM_REGISTRY}/${encodedName}`, {
+      const { data: r, isStale } = await $npmRegistry<Packument>(`/${encodedName}`, {
         signal,
       })
       const reqVer = toValue(requestedVersion)

app/composables/npm/usePackageDownloads.ts

@@ -1,18 +1,15 @@
 import type { NpmDownloadCount } from '#shared/types'
-import { NPM_API } from '~/utils/npm/common'
 
 export function usePackageDownloads(
   name: MaybeRefOrGetter<string>,
   period: MaybeRefOrGetter<'last-day' | 'last-week' | 'last-month' | 'last-year'> = 'last-week',
 ) {
-  const cachedFetch = useCachedFetch()
-
   const asyncData = useLazyAsyncData(
     () => `downloads:${toValue(name)}:${toValue(period)}`,
-    async (_nuxtApp, { signal }) => {
+    async ({ $npmApi }, { signal }) => {
       const encodedName = encodePackageName(toValue(name))
-      const { data, isStale } = await cachedFetch<NpmDownloadCount>(
-        `${NPM_API}/downloads/point/${toValue(period)}/${encodedName}`,
+      const { data, isStale } = await $npmApi<NpmDownloadCount>(
+        `/downloads/point/${toValue(period)}/${encodedName}`,
         { signal },
       )
       return { ...data, isStale }

app/composables/useCachedFetch.ts

@@ -1,4 +1,5 @@
 import type { CachedFetchResult } from '#shared/utils/fetch-cache-config'
+import { defu } from 'defu'
 
 /**
  * Get the cachedFetch function from the current request context.
@@ -34,9 +35,12 @@ export function useCachedFetch(): CachedFetchFunction {
     return async <T = unknown>(
       url: string,
       options: Parameters<typeof $fetch>[1] = {},
-      _ttl?: number,
+      _ttl: number = FETCH_CACHE_DEFAULT_TTL,
     ): Promise<CachedFetchResult<T>> => {
-      const data = (await $fetch<T>(url, options)) as T
+      const defaultFetchOptions: Parameters<typeof $fetch>[1] = {
+        cache: 'force-cache',
+      }
+      const data = (await $fetch<T>(url, defu(options, defaultFetchOptions))) as T
       return { data, isStale: false, cachedAt: null }
     }
   }
@@ -55,9 +59,12 @@ export function useCachedFetch(): CachedFetchFunction {
   return async <T = unknown>(
     url: string,
     options: Parameters<typeof $fetch>[1] = {},
-    _ttl?: number,
+    _ttl: number = FETCH_CACHE_DEFAULT_TTL,
   ): Promise<CachedFetchResult<T>> => {
-    const data = (await $fetch<T>(url, options)) as T
+    const defaultFetchOptions: Parameters<typeof $fetch>[1] = {
+      cache: 'force-cache',
+    }
+    const data = (await $fetch<T>(url, defu(options, defaultFetchOptions))) as T
     return { data, isStale: false, cachedAt: null }
   }
 }

app/pages/search.vue

@@ -316,8 +316,6 @@ interface ValidatedSuggestion {
 /** Cache for existence checks to avoid repeated API calls */
 const existenceCache = ref<Record<string, boolean | 'pending'>>({})
 
-const NPM_REGISTRY = 'https://registry.npmjs.org'
-
 interface NpmSearchResponse {
   total: number
   objects: Array<{ package: { name: string } }>

app/plugins/npm.ts

@@ -0,0 +1,22 @@
+export default defineNuxtPlugin(() => {
+  const cachedFetch = useCachedFetch()
+
+  return {
+    provide: {
+      npmRegistry: <T>(
+        url: Parameters<CachedFetchFunction>[0],
+        options?: Parameters<CachedFetchFunction>[1],
+        ttl?: Parameters<CachedFetchFunction>[2],
+      ) => {
+        return cachedFetch<T>(url, { baseURL: NPM_REGISTRY, ...options }, ttl)
+      },
+      npmApi: <T>(
+        url: Parameters<CachedFetchFunction>[0],
+        options?: Parameters<CachedFetchFunction>[1],
+        ttl?: Parameters<CachedFetchFunction>[2],
+      ) => {
+        return cachedFetch<T>(url, { baseURL: NPM_API, ...options }, ttl)
+      },
+    },
+  }
+})

app/utils/npm/api.ts

@@ -1,7 +1,6 @@
 import type { PackageVersionInfo } from '#shared/types'
 import { getVersions } from 'fast-npm-meta'
 import { compare } from 'semver'
-import { NPM_API } from './common'
 
 type NpmDownloadsRangeResponse = {
   start: string
@@ -19,10 +18,11 @@ export async function fetchNpmDownloadsRange(
   start: string,
   end: string,
 ): Promise<NpmDownloadsRangeResponse> {
+  const { $npmApi } = useNuxtApp()
   const encodedName = encodePackageName(packageName)
-  return await $fetch<NpmDownloadsRangeResponse>(
-    `${NPM_API}/downloads/range/${start}:${end}/${encodedName}`,
-  )
+  return (
+    await $npmApi<NpmDownloadsRangeResponse>(`/downloads/range/${start}:${end}/${encodedName}`)
+  ).data
 }
 
 // ============================================================================

app/utils/npm/common.ts

@@ -1,6 +1,3 @@
-export const NPM_REGISTRY = 'https://registry.npmjs.org'
-export const NPM_API = 'https://api.npmjs.org'
-
 /**
  * Constructs a scope:team string in the format expected by npm.
  * npm operations require the format @scope:team (with @ prefix).

app/utils/package-name.ts

@@ -1,4 +1,5 @@
 import validatePackageName from 'validate-npm-package-name'
+import { NPM_REGISTRY } from '#shared/utils/constants'
 import { encodePackageName } from '#shared/utils/npm'
 
 /**
@@ -71,8 +72,6 @@ export interface CheckNameResult {
   similarPackages?: SimilarPackage[]
 }
 
-const NPM_REGISTRY = 'https://registry.npmjs.org'
-
 export async function checkPackageExists(
   name: string,
   options: Parameters<typeof $fetch>[1] = {},

package.json

@@ -119,6 +119,7 @@
     "@vitest/coverage-v8": "4.0.18",
     "@vue/test-utils": "2.4.6",
     "axe-core": "4.11.1",
+    "defu": "6.1.4",
     "eslint-plugin-regexp": "3.0.0",
     "fast-check": "4.5.3",
     "h3": "1.15.5",

shared/utils/constants.ts

@@ -12,6 +12,7 @@ export const NPMX_SITE = 'https://npmx.dev'
 export const BLUESKY_API = 'https://public.api.bsky.app/xrpc/'
 export const BLUESKY_COMMENTS_REQUEST = '/api/atproto/bluesky-comments'
 export const NPM_REGISTRY = 'https://registry.npmjs.org'
+export const NPM_API = 'https://api.npmjs.org'
 export const ERROR_PACKAGE_ANALYSIS_FAILED = 'Failed to analyze package.'
 export const ERROR_PACKAGE_VERSION_AND_FILE_FAILED = 'Version and file path are required.'
 export const ERROR_PACKAGE_REQUIREMENTS_FAILED =