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 <43081j@users.noreply.github.com>
Co-authored-by: Daniel Roe <daniel@roe.dev>

Author: 4 people

app/components/PackageReplacement.vue

@@ -0,0 +1,71 @@
+<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

@@ -0,0 +1,6 @@
+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

@@ -66,6 +66,7 @@ const {
 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)
@@ -1201,8 +1202,10 @@ function handleClick(event: MouseEvent) {
         </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

@@ -116,6 +116,15 @@
       "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

@@ -116,6 +116,15 @@
       "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

@@ -49,6 +49,7 @@
     "@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

@@ -0,0 +1,11 @@
+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
+})