feat: add module-replacements support first class

Author: lino-levan

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,5 @@
+import type { ModuleReplacement } from 'module-replacements'
+
+export function useModuleReplacement(packageName: MaybeRefOrGetter<string>) {
+  return useLazyFetch<ModuleReplacement | null>(() => `/api/replacements/${toValue(packageName)}`)
+}

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

@@ -64,6 +64,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)
@@ -820,12 +821,11 @@ defineOgImageComponent('Package', {
         </dl>
       </header>
 
-      <!-- Security vulnerabilities warning -->
-      <PackageVulnerabilities
-        v-if="displayVersion"
-        :package-name="pkg.name"
-        :version="displayVersion.version"
-        class="area-vulns"
+      <!-- Bad package warning -->
+      <PackageReplacement
+        v-if="moduleReplacement"
+        :replacement="moduleReplacement"
+        class="area-replacement"
       />
 
       <!-- Binary-only packages: Show only execute command (no install) -->
@@ -1282,6 +1282,7 @@ defineOgImageComponent('Package', {
   grid-template-columns: minmax(0, 1fr);
   grid-template-areas:
     'header'
+    'replacement'
     'install'
     'vulns'
     'sidebar'
@@ -1293,10 +1294,11 @@ defineOgImageComponent('Package', {
   .package-page {
     grid-template-columns: 2fr 1fr;
     grid-template-areas:
-      'header  header'
-      'install install'
-      'vulns   vulns'
-      'readme  sidebar';
+      'header      header'
+      'replacement replacement'
+      'install     install'
+      'vulns       vulns'
+      'readme      sidebar';
   }
 }
 
@@ -1305,17 +1307,22 @@ defineOgImageComponent('Package', {
   .package-page {
     grid-template-columns: 1fr 20rem;
     grid-template-areas:
-      'header  sidebar'
-      'install sidebar'
-      'vulns   sidebar'
-      'readme  sidebar';
+      'header      sidebar'
+      'replacement sidebar'
+      'install     sidebar'
+      'vulns       sidebar'
+      'readme      sidebar';
   }
 }
 
 .area-header {
   grid-area: header;
   overflow-x: hidden;
 }
+.area-replacement {
+  grid-area: replacement;
+  overflow-x: hidden;
+}
 .area-install {
   grid-area: install;
   overflow-x: hidden;

i18n/locales/en.json

@@ -89,6 +89,15 @@
       "version": "This version has been deprecated.",
       "no_reason": "No reason provided"
     },
+    "replacement": {
+      "title": "Heads up! You might not need this dependency.",
+      "native": "This can be replaced with {replacement}, available since Node {nodeVersion}.",
+      "simple": "{replacement} instead.",
+      "documented": "This package is pretty heavy, you should consider alternatives.",
+      "none": "This package is never needed.",
+      "learn_more": "Learn more",
+      "mdn": "MDN"
+    },
     "stats": {
       "license": "License",
       "weekly": "Weekly",

package.json

@@ -42,6 +42,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
+})