feat: add module-replacements support first class (#268)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: James Garbutt <[e-mail]>
Co-authored-by: Daniel Roe <[e-mail]>

app/components/PackageReplacement.vue

···
+<script setup lang="ts">
+import type { ModuleReplacement } from 'module-replacements'
+
+const props = defineProps<{
+  replacement: ModuleReplacement
+}>()
+
+const { t } = useI18n()
+
+const message = computed(() => {
+  switch (props.replacement.type) {
+    case 'native':
+      return t('package.replacement.native', {
+        replacement: props.replacement.replacement,
+        nodeVersion: props.replacement.nodeVersion,
+      })
+    case 'simple':
+      return t('package.replacement.simple', {
+        replacement: props.replacement.replacement,
+      })
+    case 'documented':
+      return t('package.replacement.documented')
+    case 'none':
+      return t('package.replacement.none')
+  }
+})
+
+const mdnUrl = computed(() => {
+  if (props.replacement.type !== 'native' || !props.replacement.mdnPath) return null
+  return `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/${props.replacement.mdnPath}`
+})
+
+const docPath = computed(() => {
+  if (props.replacement.type !== 'documented' || !props.replacement.docPath) return null
+  return `https://github.com/es-tooling/module-replacements/blob/main/docs/modules/${props.replacement.docPath}.md`
+})
+</script>
+
+<template>
+  <div
+    class="border border-amber-600/40 bg-amber-500/10 rounded-lg px-3 py-2 text-base text-amber-700 dark:text-amber-400"
+  >
+    <h2 class="font-medium mb-1 flex items-center gap-2">
+      <span class="i-carbon-idea w-4 h-4" aria-hidden="true" />
+      {{ $t('package.replacement.title') }}
+    </h2>
+    <p class="text-sm m-0">
+      {{ message }}
+      <a
+        v-if="mdnUrl"
+        :href="mdnUrl"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="inline-flex items-center gap-1 ml-1 underline underline-offset-4 decoration-amber-600/60 dark:decoration-amber-400/50 hover:decoration-fg transition-colors"
+      >
+        {{ $t('package.replacement.mdn') }}
+        <span class="i-carbon-launch w-3 h-3" aria-hidden="true" />
+      </a>
+      <a
+        v-if="docPath"
+        :href="docPath"
+        target="_blank"
+        rel="noopener noreferrer"
+        class="inline-flex items-center gap-1 ml-1 underline underline-offset-4 decoration-amber-600/60 dark:decoration-amber-400/50 hover:decoration-fg transition-colors"
+      >
+        {{ $t('package.replacement.learn_more') }}
+        <span class="i-carbon-launch w-3 h-3" aria-hidden="true" />
+      </a>
+    </p>
+  </div>
+</template>

app/composables/useModuleReplacement.ts

···
+import type { ModuleReplacement } from 'module-replacements'
+
+/** @public */
+export function useModuleReplacement(packageName: MaybeRefOrGetter<string>) {
+  return useLazyFetch<ModuleReplacement | null>(() => `/api/replacements/${toValue(packageName)}`)
+}

app/pages/[...package].vue

···
 onMounted(() => fetchInstallSize())
 
 const { data: packageAnalysis } = usePackageAnalysis(packageName, requestedVersion)
+const { data: moduleReplacement } = useModuleReplacement(packageName)
 
 const { data: pkg, status, error } = await usePackage(packageName, requestedVersion)
 const resolvedVersion = computed(() => pkg.value?.resolvedVersion ?? null)
···
         </div>
       </section>
 
-      <!-- Vulnerability scan - full width -->
-      <div class="area-vulns">
+      <div class="area-vulns space-y-6">
+        <!-- Bad package warning -->
+        <PackageReplacement v-if="moduleReplacement" :replacement="moduleReplacement" />
+        <!-- Vulnerability scan -->
         <ClientOnly>
           <PackageVulnerabilityTree
             v-if="displayVersion"

i18n/locales/en.json

···
       "version": "This version has been deprecated.",
       "no_reason": "No reason provided"
     },
+    "replacement": {
+      "title": "You might not need this dependency.",
+      "native": "This can be replaced with {replacement}, available since Node {nodeVersion}.",
+      "simple": "The community has flagged this package as redundant, with the advice: {replacement}.",
+      "documented": "The community has flagged this package as having more performant alternatives.",
+      "none": "This package has been flagged as no longer needed, and its functionality is likely available natively in all engines.",
+      "learn_more": "Learn more",
+      "mdn": "MDN"
+    },
     "stats": {
       "license": "License",
       "deps": "Deps",

lunaria/files/en-US.json

···
       "version": "This version has been deprecated.",
       "no_reason": "No reason provided"
     },
+    "replacement": {
+      "title": "You might not need this dependency.",
+      "native": "This can be replaced with {replacement}, available since Node {nodeVersion}.",
+      "simple": "The community has flagged this package as redundant, with the advice: {replacement}.",
+      "documented": "The community has flagged this package as having more performant alternatives.",
+      "none": "This package has been flagged as no longer needed, and its functionality is likely available natively in all engines.",
+      "learn_more": "Learn more",
+      "mdn": "MDN"
+    },
     "stats": {
       "license": "License",
       "deps": "Deps",

package.json

···
     "@shikijs/themes": "^3.21.0",
     "@vueuse/core": "^14.1.0",
     "@vueuse/nuxt": "14.1.0",
+    "module-replacements": "^2.11.0",
     "nuxt": "^4.3.0",
     "nuxt-og-image": "^5.1.13",
     "ohash": "^2.0.11",

pnpm-lock.yaml

···
       '@vueuse/nuxt':
         specifier: 14.1.0
         version: 14.1.0(magicast@0.5.1)(nuxt@4.3.0(@parcel/watcher@2.5.6)(@types/node@24.10.9)(@vue/compiler-sfc@3.5.27)(better-sqlite3@12.5.0)(cac@6.7.14)(db0@0.3.4(better-sqlite3@12.5.0))(eslint@9.39.2(jiti@2.6.1))(ioredis@5.9.2)(magicast@0.5.1)(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(rolldown@1.0.0-rc.1)(rollup@4.57.0)(terser@5.46.0)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))(vue-tsc@3.2.2(typescript@5.9.3))(yaml@2.8.2))(vue@3.5.27(typescript@5.9.3))
+      module-replacements:
+        specifier: ^2.11.0
+        version: 2.11.0
       nuxt:
         specifier: ^4.3.0
         version: 4.3.0(@parcel/watcher@2.5.6)(@types/node@24.10.9)(@vue/compiler-sfc@3.5.27)(better-sqlite3@12.5.0)(cac@6.7.14)(db0@0.3.4(better-sqlite3@12.5.0))(eslint@9.39.2(jiti@2.6.1))(ioredis@5.9.2)(magicast@0.5.1)(optionator@0.9.4)(oxlint@1.42.0(oxlint-tsgolint@0.11.2))(rolldown@1.0.0-rc.1)(rollup@4.57.0)(terser@5.46.0)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.31.1)(terser@5.46.0)(yaml@2.8.2))(vue-tsc@3.2.2(typescript@5.9.3))(yaml@2.8.2)
···
 
   mocked-exports@0.1.1:
     resolution: {integrity: sha512-aF7yRQr/Q0O2/4pIXm6PZ5G+jAd7QS4Yu8m+WEeEHGnbo+7mE36CbLSDQiXYV8bVL3NfmdeqPJct0tUlnjVSnA==}
+
+  module-replacements@2.11.0:
+    resolution: {integrity: sha512-j5sNQm3VCpQQ7nTqGeOZtoJtV3uKERgCBm9QRhmGRiXiqkf7iRFOkfxdJRZWLkqYY8PNf4cDQF/WfXUYLENrRA==}
 
   motion-dom@12.29.2:
     resolution: {integrity: sha512-/k+NuycVV8pykxyiTCoFzIVLA95Nb1BFIVvfSu9L50/6K6qNeAYtkxXILy/LRutt7AzaYDc2myj0wkCVVYAPPA==}
···
       ufo: 1.6.3
 
   mocked-exports@0.1.1: {}
+
+  module-replacements@2.11.0: {}
 
   motion-dom@12.29.2:
     dependencies:

server/api/replacements/[...pkg].get.ts

···
+import { all, type ModuleReplacement } from 'module-replacements'
+
+const replacementMap = new Map<string, ModuleReplacement>(
+  all.moduleReplacements.map(r => [r.moduleName, r]),
+)
+
+export default defineEventHandler((event): ModuleReplacement | null => {
+  const pkg = getRouterParam(event, 'pkg')
+  if (!pkg) return null
+  return replacementMap.get(pkg) ?? null
+})