feat: module replacements v3

app/components/Compare/ReplacementSuggestion.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { ModuleReplacement } from 'module-replacements'
+import { resolveDocUrl } from 'module-replacements'
 
 const props = defineProps<{
   packageName: string
@@ -14,9 +15,11 @@ const emit = defineEmits<{
   addNoDep: []
 }>()
 
-const docUrl = computed(() => {
-  if (props.replacement.type !== 'documented' || !props.replacement.docPath) return null
-  return `https://e18e.dev/docs/replacements/${props.replacement.docPath}.html`
+const docUrl = computed(() => resolveDocUrl(props.replacement.url))
+
+const nodeVersion = computed(() => {
+  const nodeEngine = props.replacement.engines?.find(e => e.engine === 'nodejs')
+  return nodeEngine?.minVersion || null
 })
 </script>
 
@@ -28,6 +31,7 @@ const docUrl = computed(() => {
         ? 'bg-amber-500/10 border border-amber-600/30 text-amber-800 dark:text-amber-400'
         : 'bg-blue-500/10 border border-blue-600/30 text-blue-700 dark:text-blue-400'
     "
+    data-testid="replacement-suggestion-card"
   >
     <span
       class="w-4 h-4 flex-shrink-0 mt-0.5"
@@ -38,31 +42,38 @@ const docUrl = computed(() => {
       <p class="text-xs mt-0.5 opacity-80">
         <template v-if="replacement.type === 'native'">
           {{
-            $t('package.replacement.native', {
-              replacement: replacement.replacement,
-              nodeVersion: replacement.nodeVersion,
-            })
+            nodeVersion
+              ? $t('package.replacement.native', {
+                  replacement: replacement.description || replacement.id,
+                  nodeVersion,
+                })
+              : $t('package.replacement.native_no_version', {
+                  replacement: replacement.description || replacement.id,
+                })
           }}
         </template>
         <template v-else-if="replacement.type === 'simple'">
           {{
             $t('package.replacement.simple', {
-              replacement: replacement.replacement,
+              replacement: replacement.description,
               community: $t('package.replacement.community'),
             })
           }}
         </template>
         <template v-else-if="replacement.type === 'documented'">
           {{
             $t('package.replacement.documented', {
+              replacement: replacement.replacementModule,
               community: $t('package.replacement.community'),
             })
           }}
         </template>
+        <template v-else-if="replacement.type === 'removal'">
+          {{ replacement.description }}
+        </template>
       </p>
     </div>
 
-    <!-- No dependency action button -->
     <ButtonBase
       v-if="variant === 'nodep' && showAction !== false"
       size="sm"

app/components/Package/Replacement.vue

@@ -1,102 +1,103 @@
 <script setup lang="ts">
-import type { ModuleReplacement } from 'module-replacements'
+import type { ModuleReplacement, ModuleReplacementMapping } from 'module-replacements'
+import { resolveDocUrl } from 'module-replacements'
 
 const props = defineProps<{
+  mapping: ModuleReplacementMapping
   replacement: ModuleReplacement
 }>()
 
-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 externalUrl = computed(() => resolveDocUrl(props.mapping.url ?? props.replacement.url))
 
-const docPath = computed(() => {
-  if (props.replacement.type !== 'documented' || !props.replacement.docPath) return null
-  return `https://e18e.dev/docs/replacements/${props.replacement.docPath}.html`
+const nodeVersion = computed(() => {
+  const nodeEngine = props.replacement.engines?.find(e => e.engine === 'nodejs')
+  return nodeEngine?.minVersion || null
 })
+
+const replacementDescription =
+  props.replacement.type === 'documented'
+    ? null
+    : useMarkdown(() => ({
+        text: props.replacement.description ?? '',
+      }))
 </script>
 
 <template>
   <div
     class="border border-amber-600/40 bg-amber-500/10 rounded-lg px-3 py-2 text-base text-amber-800 dark:text-amber-400"
+    data-testid="replacement-card"
   >
     <h2 class="font-medium mb-1 flex items-center gap-2">
       <span class="i-lucide:lightbulb w-4 h-4" aria-hidden="true" />
       {{ $t('package.replacement.title') }}
     </h2>
-    <p class="text-sm m-0">
-      <i18n-t
-        v-if="replacement.type === 'native'"
-        keypath="package.replacement.native"
-        scope="global"
-      >
-        <template #replacement>
-          {{ replacement.replacement }}
-        </template>
-        <template #nodeVersion>
-          {{ replacement.nodeVersion }}
-        </template>
-      </i18n-t>
-      <i18n-t
-        v-else-if="replacement.type === 'simple'"
-        keypath="package.replacement.simple"
-        scope="global"
-      >
-        <template #community>
-          <a
-            href="https://e18e.dev/docs/replacements/"
-            target="_blank"
-            rel="noopener noreferrer"
-            class="inline-flex items-center gap-1 ms-1 underline underline-offset-4 decoration-amber-600/60 dark:decoration-amber-400/50 hover:decoration-fg transition-colors"
-          >
-            {{ $t('package.replacement.community') }}
-            <span class="i-lucide:external-link w-3 h-3" aria-hidden="true" />
-          </a>
-        </template>
-        <template #replacement>
-          {{ replacement.replacement }}
-        </template>
-      </i18n-t>
-      <i18n-t
-        v-else-if="replacement.type === 'documented'"
-        keypath="package.replacement.documented"
-        scope="global"
-      >
-        <template #community>
-          <a
-            href="https://e18e.dev/docs/replacements/"
-            target="_blank"
-            rel="noopener noreferrer"
-            class="inline-flex items-center gap-1 ms-1 underline underline-offset-4 decoration-amber-600/60 dark:decoration-amber-400/50 hover:decoration-fg transition-colors"
-          >
-            {{ $t('package.replacement.community') }}
-            <span class="i-lucide:external-link w-3 h-3" aria-hidden="true" />
-          </a>
-        </template>
-      </i18n-t>
-      <template v-else>
-        {{ $t('package.replacement.none') }}
+    <i18n-t
+      v-if="nodeVersion && replacement.type === 'native'"
+      keypath="package.replacement.native"
+      scope="global"
+    >
+      <template #replacement>
+        <span v-if="replacementDescription" v-html="replacementDescription" />
+        <span v-else>{{ replacement.id }}</span>
+      </template>
+      <template #nodeVersion>
+        {{ nodeVersion }}
+      </template>
+    </i18n-t>
+    <i18n-t
+      v-else-if="replacement.type === 'native'"
+      keypath="package.replacement.native_no_version"
+      scope="global"
+    >
+      <template #replacement>
+        <span v-if="replacementDescription" v-html="replacementDescription" />
+        <span v-else>{{ replacement.id }}</span>
+      </template>
+    </i18n-t>
+    <div v-else-if="replacement.type === 'simple'" class="block">
+      <div class="mb-2" v-html="replacementDescription" />
+      <div v-if="replacement.example">
+        <strong class="block mb-1.5">{{ $t('package.replacement.example') }}</strong>
+        <pre
+          class="bg-amber-800/10 dark:bg-amber-950/30 p-2 rounded border border-amber-700/20 overflow-x-auto text-xs font-mono leading-relaxed"
+        ><code>{{ replacement.example }}</code></pre>
+      </div>
+    </div>
+    <i18n-t
+      v-else-if="replacement.type === 'documented'"
+      keypath="package.replacement.documented"
+      scope="global"
+    >
+      <template #replacement>
+        <code>{{ replacement.replacementModule }}</code>
+      </template>
+      <template #community>
+        <a
+          href="https://e18e.dev/docs/replacements/"
+          target="_blank"
+          rel="noopener noreferrer"
+          class="inline-flex items-center gap-1 ms-1 underline underline-offset-4 decoration-amber-600/60 dark:decoration-amber-400/50 hover:decoration-fg transition-colors"
+        >
+          {{ $t('package.replacement.community') }}
+          <span class="i-lucide:external-link w-3 h-3" aria-hidden="true" />
+        </a>
       </template>
-      <a
-        v-if="mdnUrl"
-        :href="mdnUrl"
-        target="_blank"
-        rel="noopener noreferrer"
-        class="inline-flex items-center gap-1 ms-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-lucide:external-link 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 ms-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-lucide:external-link w-3 h-3" aria-hidden="true" />
-      </a>
-    </p>
+    </i18n-t>
+    <template v-else-if="replacement.type === 'removal'">
+      <span v-html="replacementDescription" />
+    </template>
+    <template v-else>
+      {{ $t('package.replacement.none') }}
+    </template>
+    <a
+      v-if="externalUrl"
+      :href="externalUrl"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="inline-flex items-center gap-1 ms-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-lucide:external-link w-3 h-3" aria-hidden="true" />
+    </a>
   </div>
 </template>

app/composables/npm/useReplacementDependencies.ts

@@ -1,4 +1,4 @@
-import type { ModuleReplacement } from 'module-replacements'
+import type { ModuleReplacement, ModuleReplacementMapping } from 'module-replacements'
 
 async function fetchReplacements(
   deps: Record<string, string>,
@@ -8,7 +8,11 @@ async function fetchReplacements(
   const results = await Promise.all(
     names.map(async name => {
       try {
-        const replacement = await $fetch<ModuleReplacement | null>(`/api/replacements/${name}`)
+        const response = await $fetch<{
+          mapping: ModuleReplacementMapping
+          replacement: ModuleReplacement
+        } | null>(`/api/replacements/${name}`)
+        const replacement = response?.replacement ?? null
         return { name, replacement }
       } catch {
         return { name, replacement: null }

app/composables/useCompareReplacements.ts

@@ -1,4 +1,4 @@
-import type { ModuleReplacement } from 'module-replacements'
+import type { ModuleReplacement, ModuleReplacementMapping } from 'module-replacements'
 
 export interface ReplacementSuggestion {
   forPackage: string
@@ -41,8 +41,11 @@ export function useCompareReplacements(packageNames: MaybeRefOrGetter<string[]>)
       const results = await Promise.all(
         namesToCheck.map(async name => {
           try {
-            const replacement = await $fetch<ModuleReplacement | null>(`/api/replacements/${name}`)
-            return { name, replacement }
+            const result = await $fetch<{
+              mapping: ModuleReplacementMapping
+              replacement: ModuleReplacement
+            } | null>(`/api/replacements/${name}`)
+            return { name, replacement: result?.replacement ?? null }
           } catch {
             return { name, replacement: null }
           }
@@ -99,9 +102,9 @@ export function useCompareReplacements(packageNames: MaybeRefOrGetter<string[]>)
   )
 
   return {
-    replacements: readonly(replacements),
-    noDepSuggestions: readonly(noDepSuggestions),
-    infoSuggestions: readonly(infoSuggestions),
+    replacements,
+    noDepSuggestions,
+    infoSuggestions,
     loading: readonly(loading),
   }
 }

app/composables/useModuleReplacement.ts

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

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

@@ -884,7 +884,11 @@ const showSkeleton = shallowRef(false)
 
         <div class="space-y-6" :class="$style.areaVulns">
           <!-- Bad package warning -->
-          <PackageReplacement v-if="moduleReplacement" :replacement="moduleReplacement" />
+          <PackageReplacement
+            v-if="moduleReplacement"
+            :mapping="moduleReplacement.mapping"
+            :replacement="moduleReplacement.replacement"
+          />
           <!-- Size / dependency increase notice -->
           <PackageSizeIncrease v-if="sizeDiff" :diff="sizeDiff" />
           <!-- Vulnerability scan -->

i18n/locales/ar.json

@@ -178,7 +178,6 @@
       "none": "تم وضع علامة على هذه الحزمة بأنها لم تعد مطلوبة، ومن المرجح أن وظيفتها متاحة أصلًا في جميع المحركات.",
       "learn_more": "اعرف المزيد",
       "learn_more_above": "اعرف المزيد أعلاه.",
-      "mdn": "MDN",
       "community": "المجتمع",
       "consider_no_dep": "+ هل تريد خيار «بدون تبعية»؟"
     },

i18n/locales/az-AZ.json

@@ -243,7 +243,6 @@
       "none": "Bu paket artıq lazımsız olaraq qeyd edilib və funksionallığı bütün mühərriklərdə yerli olaraq mövcuddur.",
       "learn_more": "Ətraflı öyrən",
       "learn_more_above": "Yuxarıda ətraflı öyrənin.",
-      "mdn": "MDN",
       "community": "icma",
       "consider_no_dep": "+ Asılılıqsız düşünün?"
     },

i18n/locales/bg-BG.json

@@ -206,7 +206,6 @@
       "none": "Този пакет е отбелязан като вече ненужен и функционалността му вероятно е налична нативно във всички двигатели.",
       "learn_more": "Научете повече",
       "learn_more_above": "Научете повече по-горе.",
-      "mdn": "MDN",
       "community": "общност",
       "consider_no_dep": "+ Обмислете без зависимости?"
     },

i18n/locales/bn-IN.json

@@ -143,7 +143,6 @@
       "documented": "{community} এই প্যাকেজটিকে আরো ভাল পারফরম্যান্স অপশন হিসাবে চিহ্নিত করেছে।",
       "none": "এই প্যাকেজটি এখন অনাবশ্যক হিসাবে চিহ্নিত, এবং এর কার্যকরিতা সমস্ত ইঞ্জিনে নেটিভভাবে উপলব্ধ হওয়ার সম্ভাবনা আছে।",
       "learn_more": "আরো জানুন",
-      "mdn": "MDN",
       "community": "কমিউনিটি"
     },
     "stats": {

i18n/locales/cs-CZ.json

@@ -253,7 +253,6 @@
       "none": "Tento balíček byl označen jako již nepotřebný a jeho funkčnost je pravděpodobně dostupná nativně ve všech enginech.",
       "learn_more": "Zjistit více",
       "learn_more_above": "Zjistit více výše.",
-      "mdn": "MDN",
       "community": "komunita",
       "consider_no_dep": "+ Zvážit žádnou závislost?"
     },

i18n/locales/de.json

@@ -272,7 +272,6 @@
       "none": "Dieses Paket wurde als nicht mehr nötig markiert, und seine Funktionalität ist wahrscheinlich in allen Engines nativ verfügbar.",
       "learn_more": "Mehr erfahren",
       "learn_more_above": "Erfahre oben mehr.",
-      "mdn": "MDN",
       "community": "Community",
       "consider_no_dep": "+ Ohne Abhängigkeit lösen?"
     },

i18n/locales/en.json

@@ -267,13 +267,14 @@
     },
     "replacement": {
       "title": "You might not need this dependency.",
+      "example": "Example:",
       "native": "This can be replaced with {replacement}, available since Node {nodeVersion}.",
-      "simple": "The {community} has flagged this package as redundant, with the advice: {replacement}.",
+      "native_no_version": "This can be replaced with {replacement}.",
+      "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",
       "learn_more_above": "Learn more above.",
-      "mdn": "MDN",
       "community": "community",
       "consider_no_dep": "+ Consider no dep?"
     },