feat: module replacements v3

app/components/Compare/ReplacementSuggestion.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { ModuleReplacement } from 'module-replacements'
+import { resolveReplacementUrl } from '~/utils/resolve-replacement-url'
 
 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(() => resolveReplacementUrl(props.replacement.url))
+
+const nodeVersion = computed(() => {
+  const nodeEngine = props.replacement.engines?.find(e => e.engine === 'nodejs')
+  return nodeEngine?.minVersion || null
 })
 </script>
 
@@ -38,31 +41,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="small"
@@ -72,7 +82,6 @@ const docUrl = computed(() => {
       {{ $t('package.replacement.consider_no_dep') }}
     </ButtonBase>
 
-    <!-- Info link -->
     <LinkBase v-else-if="docUrl" :to="docUrl" variant="button-secondary" size="small">
       {{ $t('package.replacement.learn_more') }}
     </LinkBase>

app/components/Package/Replacement.vue

@@ -1,18 +1,19 @@
 <script setup lang="ts">
-import type { ModuleReplacement } from 'module-replacements'
+import type { ModuleReplacement, ModuleReplacementMapping } from 'module-replacements'
+import { resolveReplacementUrl } from '~/utils/resolve-replacement-url'
 
 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(() =>
+  resolveReplacementUrl(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
 })
 </script>
 
@@ -24,79 +25,77 @@ const docPath = computed(() => {
       <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>
+        <code v-if="replacement.description">
+          {{ replacement.description }}
+        </code>
+        <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>
+        <code v-if="replacement.description">
+          {{ replacement.description }}
+        </code>
+        <span v-else>{{ replacement.id }}</span>
+      </template>
+    </i18n-t>
+    <div v-else-if="replacement.type === 'simple'" class="block">
+      <div class="mb-2">{{ replacement.description }}</div>
+      <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'">
+      {{ replacement.description }}
+    </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

@@ -8,7 +8,7 @@
   const results = await Promise.all(
     names.map(async name => {
       try {
-        const replacement = await $fetch<ModuleReplacement | null>(`/api/replacements/${name}`)
+        const { replacement } = await $fetch<ModuleReplacement | null>(`/api/replacements/${name}`)
         return { name, replacement }
       } catch {
         return { name, replacement: null }

app/composables/useCompareReplacements.ts

@@ -99,9 +99,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

@@ -876,7 +876,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/resolve-replacement-url.ts

@@ -0,0 +1,17 @@
+import type { KnownUrl } from 'module-replacements'
+
+export function resolveReplacementUrl(url?: KnownUrl): string | null {
+  if (!url) return null
+  if (typeof url === 'string') return url
+
+  switch (url.type) {
+    case 'mdn':
+      return `https://developer.mozilla.org/en-US/docs/${url.id}`
+    case 'node':
+      return `https://nodejs.org/${url.id}`
+    case 'e18e':
+      return `https://e18e.dev/docs/replacements/${url.id}`
+    default:
+      return null
+  }
+}