feat: module replacements v3

app/components/Compare/ReplacementSuggestion.vue

@@ -1,5 +1,7 @@
 <script setup lang="ts">
 import type { ModuleReplacement } from 'module-replacements'
+import { resolveDocUrl } from 'module-replacements'
+import { getReplacementDescription, getReplacementNodeVersion } from '~/utils/module-replacements'
 
 const props = defineProps<{
   packageName: string
@@ -14,10 +16,13 @@ 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(() => getReplacementNodeVersion(props.replacement))
+
+const replacementDescription = useMarkdown(() => ({
+  text: getReplacementDescription(props.replacement),
+}))
 </script>
 
 <template>
@@ -28,6 +33,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"
@@ -36,33 +42,65 @@ const docUrl = computed(() => {
     <div class="min-w-0 flex-1">
       <p class="font-medium">{{ packageName }}: {{ $t('package.replacement.title') }}</p>
       <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,
-            })
-          }}
-        </template>
+        <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
+              ><code>{{ replacement.id }}</code></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
+              ><code>{{ replacement.id }}</code></span
+            >
+          </template>
+        </i18n-t>
         <template v-else-if="replacement.type === 'simple'">
-          {{
-            $t('package.replacement.simple', {
-              replacement: replacement.replacement,
-              community: $t('package.replacement.community'),
-            })
-          }}
+          <i18n-t keypath="package.replacement.simple">
+            <template #replacement><span v-html="replacementDescription" /></template>
+            <template #community>{{ $t('package.replacement.community') }}</template>
+          </i18n-t>
         </template>
-        <template v-else-if="replacement.type === 'documented'">
-          {{
-            $t('package.replacement.documented', {
-              community: $t('package.replacement.community'),
-            })
-          }}
+        <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>
+        </i18n-t>
+        <template v-else-if="replacement.type === 'removal'">
+          <span v-html="replacementDescription" />
         </template>
       </p>
     </div>
 
-    <!-- No dependency action button -->
     <ButtonBase
       v-if="variant === 'nodep' && showAction !== false"
       size="sm"

app/components/Package/Replacement.vue

@@ -1,67 +1,67 @@
 <script setup lang="ts">
-import type { ModuleReplacement } from 'module-replacements'
+import type { ModuleReplacement, ModuleReplacementMapping } from 'module-replacements'
+import { resolveDocUrl } from 'module-replacements'
+import { getReplacementDescription, getReplacementNodeVersion } from '~/utils/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(() => getReplacementNodeVersion(props.replacement))
+
+const replacementDescription = useMarkdown(() => ({
+  text: getReplacementDescription(props.replacement),
+}))
 </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">
+    <p>
       <i18n-t
-        v-if="replacement.type === 'native'"
+        v-if="nodeVersion && replacement.type === 'native'"
         keypath="package.replacement.native"
         scope="global"
       >
         <template #replacement>
-          {{ replacement.replacement }}
+          <span v-if="replacementDescription" v-html="replacementDescription" />
+          <span v-else
+            ><code>{{ replacement.id }}</code></span
+          >
         </template>
         <template #nodeVersion>
-          {{ replacement.nodeVersion }}
+          {{ nodeVersion }}
         </template>
       </i18n-t>
       <i18n-t
-        v-else-if="replacement.type === 'simple'"
-        keypath="package.replacement.simple"
+        v-else-if="replacement.type === 'native'"
+        keypath="package.replacement.native_no_version"
         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 }}
+          <span v-if="replacementDescription" v-html="replacementDescription" />
+          <span v-else
+            ><code>{{ replacement.id }}</code></span
+          >
         </template>
       </i18n-t>
       <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/"
@@ -74,22 +74,18 @@ const docPath = computed(() => {
           </a>
         </template>
       </i18n-t>
+      <template v-else-if="replacement.type === 'removal'">
+        <span v-html="replacementDescription" />
+      </template>
+      <template v-else-if="replacement.type === 'simple'">
+        <span v-html="replacementDescription" />
+      </template>
       <template v-else>
         {{ $t('package.replacement.none') }}
       </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"
+        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"
@@ -98,5 +94,11 @@ const docPath = computed(() => {
         <span class="i-lucide:external-link w-3 h-3" aria-hidden="true" />
       </a>
     </p>
+    <div v-if="replacement.type === 'simple' && 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>
 </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
@@ -8,13 +8,17 @@ export interface ReplacementSuggestion {
 /**
  * Replacement types that suggest "no dependency" (can be replaced with native code or inline).
  */
-const NO_DEP_REPLACEMENT_TYPES = ['native', 'simple'] as const
+const NO_DEP_REPLACEMENT_TYPES = [
+  'native',
+  'simple',
+  'removal',
+] as const satisfies ModuleReplacement['type'][]
 
 /**
  * Replacement types that are informational only.
  * These suggest alternative packages exist but don't fit the "no dependency" pattern.
  */
-const INFO_REPLACEMENT_TYPES = ['documented'] as const
+const INFO_REPLACEMENT_TYPES = ['documented'] as const satisfies ModuleReplacement['type'][]
 
 /**
  * Composable for fetching module replacement suggestions for packages in comparison.
@@ -41,8 +45,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 +106,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

@@ -906,7 +906,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 -->

app/utils/module-replacements.ts

@@ -0,0 +1,11 @@
+import type { ModuleReplacement } from 'module-replacements'
+
+export function getReplacementDescription(replacement: ModuleReplacement): string {
+  if (replacement.type === 'documented') return ''
+  return replacement.description ?? ''
+}
+
+export function getReplacementNodeVersion(replacement: ModuleReplacement): string | null {
+  const nodeEngine = replacement.engines?.find(e => e.engine === 'nodejs')
+  return nodeEngine?.minVersion || null
+}

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": {