From beef63971232522a7539652492396cd18672d9ca Mon Sep 17 00:00:00 2001
From: Ivan Bochkarev <ivanx86@gmail.com>
Date: Mon, 20 Jul 2026 15:23:11 +0600
Subject: [PATCH 1/3] feat(modules): show Nuxt version compatibility on modules
 page

---
 app/components/module/ModuleItem.vue    | 14 +++++++
 app/composables/useModules.ts           | 55 +++++++++++++++++++++----
 app/pages/modules/[slug].vue            | 24 +++++++++--
 app/pages/modules/index.vue             | 28 ++++++++++---
 package.json                            |  1 +
 pnpm-lock.yaml                          |  3 ++
 server/api/v1/modules/index.get.ts      | 17 +++-----
 shared/utils/modules-query.ts           | 44 ++++++++++++++++++++
 shared/utils/modules.ts                 | 32 ++++++++++++++
 test/browser/modules.spec.ts            | 15 +++++++
 test/unit/modules-compatibility.spec.ts | 48 +++++++++++++++++++++
 test/unit/modules-query.spec.ts         | 28 +++++++++++++
 12 files changed, 279 insertions(+), 30 deletions(-)
 create mode 100644 shared/utils/modules-query.ts
 create mode 100644 shared/utils/modules.ts
 create mode 100644 test/unit/modules-compatibility.spec.ts
 create mode 100644 test/unit/modules-query.spec.ts

diff --git a/app/components/module/ModuleItem.vue b/app/components/module/ModuleItem.vue
index 21062cf3a..0707f7191 100644
--- a/app/components/module/ModuleItem.vue
+++ b/app/components/module/ModuleItem.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { Module } from '#shared/types'
+import { getModuleNuxtMajors } from '#shared/utils/modules'
 
 const emit = defineEmits<{
   add: [module: Module]
@@ -23,6 +24,8 @@ const { copy } = useClipboard()
 const { selectedSort } = useModules()
 const { track } = useAnalytics()
 
+const nuxtMajors = computed(() => getModuleNuxtMajors(props.module.compatibility?.nuxt))
+
 const publishedAgo = useTimeAgo(() => props.module.stats.publishedAt)
 const createdAgo = useTimeAgo(() => props.module.stats.createdAt)
 
@@ -144,6 +147,17 @@ const items = computed(() => [
 
         <div class="flex items-center justify-between gap-3 -my-1 text-muted">
           <div class="flex items-center gap-3 flex-wrap">
+            <div v-if="nuxtMajors.length" class="flex items-center gap-1">
+              <UBadge
+                v-for="major in nuxtMajors"
+                :key="major"
+                :label="`Nuxt ${major}`"
+                color="neutral"
+                variant="subtle"
+                size="sm"
+              />
+            </div>
+
             <UTooltip text="Monthly NPM Downloads">
               <NuxtLink
                 class="flex items-center gap-1 hover:text-highlighted"
diff --git a/app/composables/useModules.ts b/app/composables/useModules.ts
index 768d20454..3e351bed1 100644
--- a/app/composables/useModules.ts
+++ b/app/composables/useModules.ts
@@ -1,5 +1,6 @@
 type ModuleStatsKeys = 'version' | 'downloads' | 'stars' | 'publishedAt' | 'createdAt'
 import type { Module } from '#shared/types'
+import { moduleSupportsNuxt } from '#shared/utils/modules'
 import type { Filter } from '~/types'
 
 const iconsMap = {
@@ -42,8 +43,28 @@ export const moduleIcon = function (category: string) {
 export const useModules = () => {
   const route = useRoute()
   const router = useRouter()
-  const { data, execute } = useFetch('/api/v1/modules', {
+
+  const versions: Filter[] = [
+    { key: '3', label: 'Nuxt 3' },
+    { key: '4', label: 'Nuxt 4' },
+    { key: 'all', label: 'All' }
+  ]
+
+  const selectedVersion = computed(() => {
+    const raw = route.query.version
+    const key = raw == null || raw === ''
+      ? undefined
+      : String(Array.isArray(raw) ? raw[0] : raw)
+    return versions.find(version => version.key === key) || versions[0]
+  })
+
+  // Always fetch the full catalog once, then filter by major on the client.
+  // Production still rejects `version=4`, and switching API version clears the
+  // list during refetch (empty flash / stuck empty after hydration).
+  const { data, execute, status } = useFetch('/api/v1/modules', {
+    key: 'modules-catalog',
     immediate: false,
+    query: { version: 'all' },
     default: () => ({
       modules: [],
       stats: {
@@ -61,7 +82,12 @@ export const useModules = () => {
 
   // Data fetching
   async function fetchList() {
-    if (modules.value.length) {
+    if (status.value === 'pending') {
+      return
+    }
+    // Re-fetch when the result is empty. Large `/api/v1/modules` responses may
+    // not hydrate into the client payload, leaving status=success with [].
+    if (status.value === 'success' && (data.value?.modules?.length ?? 0) > 0) {
       return
     }
 
@@ -89,7 +115,14 @@ export const useModules = () => {
           key: category,
           label: category,
           active: route.query.category === category,
-          to: { name: 'modules', query: category === route.query.category ? undefined : { category }, state: { smooth: '#smooth' } },
+          to: {
+            name: 'modules',
+            query: {
+              ...route.query,
+              category: category === route.query.category ? undefined : category
+            },
+            state: { smooth: '#smooth' }
+          },
           icon: iconsMap[category as keyof typeof iconsMap] || undefined,
           click: (e: Event) => {
             if (route.query.category !== category) {
@@ -135,8 +168,16 @@ export const useModules = () => {
   }
 
   const filteredModules = computed<Module[]>(() => {
+    const versionKey = selectedVersion.value?.key
+    const versionMajor = versionKey === '3' || versionKey === '4'
+      ? Number(versionKey) as 3 | 4
+      : null
+
     let filteredModules = [...modules.value]
       .filter((module: Module) => {
+        if (versionMajor && !moduleSupportsNuxt(module.compatibility?.nuxt, versionMajor)) {
+          return false
+        }
         if (selectedCategory.value) {
           if (selectedCategory.value.key === 'Official') {
             return module.type === 'official'
@@ -175,7 +216,7 @@ export const useModules = () => {
     // Data fetching
     fetchList,
     // Data
-    // versions,
+    versions,
     sorts,
     orders,
     // Computed
@@ -184,12 +225,8 @@ export const useModules = () => {
     filteredModules,
     module,
     categories,
-    // types,
-    // contributors,
-    // stats,
     selectedCategory,
-    // selectedType,
-    // selectedVersion,
+    selectedVersion,
     selectedSort,
     selectedOrder,
     q
diff --git a/app/pages/modules/[slug].vue b/app/pages/modules/[slug].vue
index 413615acf..5b3824626 100644
--- a/app/pages/modules/[slug].vue
+++ b/app/pages/modules/[slug].vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import type { Module } from '#shared/types'
+import { getModuleNuxtMajors, moduleSupportsNuxt } from '#shared/utils/modules'
 import { ModuleProseA, ModuleProseKbd, ModuleProseImg } from '#components'
 
 definePageMeta({
@@ -13,6 +14,12 @@ if (!module.value) {
   throw createError({ statusCode: 404, statusMessage: 'Module not found', fatal: true })
 }
 
+const nuxtMajors = computed(() => getModuleNuxtMajors(module.value?.compatibility?.nuxt))
+const isLegacyNuxtModule = computed(() => {
+  const range = module.value?.compatibility?.nuxt
+  return !moduleSupportsNuxt(range, 3) && !moduleSupportsNuxt(range, 4)
+})
+
 const ownerName = computed(() => {
   const [owner, name] = module.value!.repo.split('#')[0].split('/')
   return `${owner}/${name}`
@@ -95,11 +102,11 @@ if (import.meta.server) {
 
 <template>
   <UContainer v-if="module">
-    <div v-if="!module.compatibility?.nuxt?.includes('^3') && !module.compatibility?.nuxt?.includes('>=3')" class="pt-8">
+    <div v-if="isLegacyNuxtModule" class="pt-8">
       <UAlert
         icon="i-lucide-triangle-alert"
         variant="subtle"
-        title="This module is not yet compatible with Nuxt 3"
+        title="This module is not compatible with Nuxt 3 or Nuxt 4"
       >
         <template #description>
           Head over to <NuxtLink to="https://v2.nuxt.com" target="_blank" class="underline">
@@ -122,12 +129,21 @@ if (import.meta.server) {
             class="-m-[4px] rounded-none bg-transparent"
           />
 
-          <div>
-            {{ module.npm }}
+          <div class="flex flex-wrap items-center gap-2">
+            <span>{{ module.npm }}</span>
 
             <UTooltip v-if="module.type === 'official'" text="Official module" class="tracking-normal">
               <UIcon name="i-lucide-medal" class="size-6 text-primary" />
             </UTooltip>
+
+            <UBadge
+              v-for="major in nuxtMajors"
+              :key="major"
+              :label="`Nuxt ${major}`"
+              color="neutral"
+              variant="subtle"
+              size="sm"
+            />
           </div>
         </div>
       </template>
diff --git a/app/pages/modules/index.vue b/app/pages/modules/index.vue
index c31fcaabf..ade7e52c3 100644
--- a/app/pages/modules/index.vue
+++ b/app/pages/modules/index.vue
@@ -12,7 +12,7 @@ const modulesToAdd = ref<Module[]>([])
 const el = useTemplateRef<HTMLElement>('el')
 
 const { replaceRoute } = useFilters('modules')
-const { fetchList, filteredModules, q, categories, modules, stats, selectedSort, selectedOrder, selectedCategory, sorts } = useModules()
+const { fetchList, filteredModules, q, categories, modules, stats, selectedSort, selectedOrder, selectedCategory, selectedVersion, sorts, versions } = useModules()
 const { track } = useAnalytics()
 
 const cacheControl = useResponseHeader('Cache-Control')
@@ -95,9 +95,8 @@ watch(scrollY, (y) => {
 
 watch(filteredModules, () => {
   isLoading.value = false
-  displayedModules.value = []
   initializeModules()
-})
+}, { immediate: true })
 
 const copyAllInstallCommands = () => {
   const moduleNames = modulesToAdd.value.map(module => module.name).join(' ')
@@ -137,8 +136,6 @@ Steps:
 const clearAllModules = () => {
   modulesToAdd.value = []
 }
-
-initializeModules()
 </script>
 
 <template>
@@ -155,7 +152,7 @@ initializeModules()
       }"
     >
       <template #title>
-        Build faster with <span class="text-primary">{{ modules.length }}+</span> Nuxt Modules
+        Build faster with <span class="text-primary">{{ filteredModules.length }}+</span> Nuxt Modules
       </template>
 
       <template #description>
@@ -192,6 +189,16 @@ initializeModules()
             </UInput>
 
             <div class="hidden sm:flex gap-2 sm:w-auto">
+              <USelectMenu
+                :model-value="selectedVersion"
+                :items="versions"
+                size="lg"
+                color="neutral"
+                class="w-auto"
+                variant="outline"
+                @update:model-value="replaceRoute('version', $event)"
+              />
+
               <USelectMenu
                 :model-value="selectedSort"
                 :items="sorts"
@@ -234,6 +241,15 @@ initializeModules()
               aria-label="Clear category filter"
               @click="replaceRoute('category', '')"
             />
+            <USelectMenu
+              :model-value="selectedVersion"
+              :items="versions"
+              size="lg"
+              color="neutral"
+              class="w-auto"
+              variant="outline"
+              @update:model-value="replaceRoute('version', $event)"
+            />
             <USelectMenu
               :model-value="selectedSort"
               :items="sorts"
diff --git a/package.json b/package.json
index 6da296ff8..7ebfcdd7b 100644
--- a/package.json
+++ b/package.json
@@ -70,6 +70,7 @@
     "ofetch": "^1.5.1",
     "resend": "^6.17.2",
     "scule": "^1.3.0",
+    "semver": "^7.8.5",
     "shaders": "^2.5.135",
     "sitemap": "^9.0.1",
     "std-env": "^4.2.0",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 15d2f8a72..8c8c1078b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -149,6 +149,9 @@ importers:
       scule:
         specifier: ^1.3.0
         version: 1.3.0
+      semver:
+        specifier: ^7.8.5
+        version: 7.8.5
       shaders:
         specifier: ^2.5.135
         version: 2.5.135(vue@3.5.39(typescript@6.0.3))
diff --git a/server/api/v1/modules/index.get.ts b/server/api/v1/modules/index.get.ts
index a9c14b9eb..f514b052d 100644
--- a/server/api/v1/modules/index.get.ts
+++ b/server/api/v1/modules/index.get.ts
@@ -1,18 +1,14 @@
-import { z } from 'zod'
-import { satisfies } from 'semver'
+import { moduleSupportsNuxt } from '#shared/utils/modules'
+import { modulesCacheKey, normalizeModulesQuery } from '#shared/utils/modules-query'
 
 export default defineCachedEventHandler(async (event) => {
-  const { version, category } = await getValidatedQuery(event, z.object({
-    version: z.enum(['2', '2-bridge', '3', 'all']).default('3'),
-    category: z.string().optional()
-  }).parse)
+  const { version, category } = normalizeModulesQuery(getQuery(event) as Record<string, unknown>)
   console.log(`Fetching v${version} modules...${category ? ` for category: ${category}` : ''}`)
 
   let modules = await fetchModules(event) || []
 
   if (version !== 'all') {
-    const major = (version === '2-bridge' ? '2' : version) satisfies '2' | '3'
-    const testableVersion = `${major}.999.999`
+    const major = (version === '2-bridge' ? 2 : Number(version)) as 2 | 3 | 4
 
     // Filter out modules by compatibility
     modules = modules.filter((module) => {
@@ -20,7 +16,7 @@ export default defineCachedEventHandler(async (event) => {
       if (version === '2-bridge' && !module.compatibility.requires?.bridge) {
         return false
       }
-      return satisfies(testableVersion, module.compatibility.nuxt)
+      return moduleSupportsNuxt(module.compatibility.nuxt, major)
     })
   }
 
@@ -101,8 +97,7 @@ export default defineCachedEventHandler(async (event) => {
   name: 'modules',
   swr: true,
   getKey(event) {
-    const query = getQuery(event)
-    return `${query?.version || '3'}-${query?.category || 'all'}`
+    return modulesCacheKey(getQuery(event) as Record<string, unknown>)
   },
   maxAge: 60 * 60 // 1 hour
 })
diff --git a/shared/utils/modules-query.ts b/shared/utils/modules-query.ts
new file mode 100644
index 000000000..2736feecb
--- /dev/null
+++ b/shared/utils/modules-query.ts
@@ -0,0 +1,44 @@
+import { z } from 'zod'
+
+export const modulesVersionValues = ['2', '2-bridge', '3', '4', 'all'] as const
+
+export const modulesQuerySchema = z.object({
+  version: z.enum(modulesVersionValues).default('3'),
+  category: z.string().optional()
+})
+
+export type ModulesQuery = z.infer<typeof modulesQuerySchema>
+
+/**
+ * Normalize h3 query values before Zod parse.
+ * Numeric-looking params (e.g. version=4) may arrive as numbers.
+ */
+export function normalizeModulesQuery(raw: Record<string, unknown> | undefined): ModulesQuery {
+  const versionRaw = raw?.version
+  const categoryRaw = raw?.category
+
+  return modulesQuerySchema.parse({
+    version: versionRaw == null || versionRaw === ''
+      ? undefined
+      : String(Array.isArray(versionRaw) ? versionRaw[0] : versionRaw),
+    category: typeof categoryRaw === 'string'
+      ? categoryRaw
+      : Array.isArray(categoryRaw) && typeof categoryRaw[0] === 'string'
+        ? categoryRaw[0]
+        : undefined
+  })
+}
+
+export function modulesCacheKey(raw: Record<string, unknown> | undefined): string {
+  const versionRaw = raw?.version
+  const categoryRaw = raw?.category
+  const version = versionRaw == null || versionRaw === ''
+    ? '3'
+    : String(Array.isArray(versionRaw) ? versionRaw[0] : versionRaw)
+  const category = typeof categoryRaw === 'string'
+    ? categoryRaw
+    : Array.isArray(categoryRaw) && typeof categoryRaw[0] === 'string'
+      ? categoryRaw[0]
+      : 'all'
+  return `${version}-${category || 'all'}`
+}
diff --git a/shared/utils/modules.ts b/shared/utils/modules.ts
new file mode 100644
index 000000000..8a0a73e08
--- /dev/null
+++ b/shared/utils/modules.ts
@@ -0,0 +1,32 @@
+import { satisfies } from 'semver'
+
+export type NuxtMajor = 2 | 3 | 4
+export type ModuleNuxtBadgeMajor = 3 | 4
+
+/**
+ * Whether a module's `compatibility.nuxt` semver range includes the given major.
+ * Uses the same probe version pattern as `/api/v1/modules` (`${major}.999.999`).
+ */
+export function moduleSupportsNuxt(range: string | undefined, major: NuxtMajor): boolean {
+  if (!range) {
+    return false
+  }
+
+  try {
+    return satisfies(`${major}.999.999`, range)
+  } catch {
+    return false
+  }
+}
+
+/** Majors shown as badges on the modules UI (Nuxt 3 / Nuxt 4). */
+export function getModuleNuxtMajors(range: string | undefined): ModuleNuxtBadgeMajor[] {
+  const majors: ModuleNuxtBadgeMajor[] = []
+  if (moduleSupportsNuxt(range, 3)) {
+    majors.push(3)
+  }
+  if (moduleSupportsNuxt(range, 4)) {
+    majors.push(4)
+  }
+  return majors
+}
diff --git a/test/browser/modules.spec.ts b/test/browser/modules.spec.ts
index a2ece3718..8405cf73f 100644
--- a/test/browser/modules.spec.ts
+++ b/test/browser/modules.spec.ts
@@ -55,6 +55,21 @@ test.describe('Modules Page', () => {
     expect(await moduleLinks.count()).toBeLessThanOrEqual(count)
   })
 
+  test('filters modules by Nuxt version', async ({ page, goto }) => {
+    await goto('/modules')
+
+    await page.goto('/modules?version=4')
+    await expect(page).toHaveURL(/version=4/)
+    await expect(page.getByText('Nuxt 4').first()).toBeVisible()
+
+    const moduleLinks = page.locator('a[href^="/modules/"]')
+    await expect.poll(async () => moduleLinks.count()).toBeGreaterThan(0)
+
+    await page.goto('/modules?version=all')
+    await expect(page).toHaveURL(/version=all/)
+    await expect(page.getByText('All').first()).toBeVisible()
+  })
+
   // TODO: needs to be fixed in nuxt/ui
   test.skip('navigates to module detail page', async ({ page, goto }) => {
     await goto('/modules')
diff --git a/test/unit/modules-compatibility.spec.ts b/test/unit/modules-compatibility.spec.ts
new file mode 100644
index 000000000..420c2a88e
--- /dev/null
+++ b/test/unit/modules-compatibility.spec.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { getModuleNuxtMajors, moduleSupportsNuxt } from '../../shared/utils/modules'
+
+describe('moduleSupportsNuxt against CDN registry', () => {
+  it('finds Nuxt 4 compatible modules in the live modules.json', async () => {
+    const modules = await fetch('https://unpkg.com/@nuxt/modules@latest/modules.json')
+      .then(res => res.json()) as Array<{ name: string, compatibility?: { nuxt?: string } }>
+
+    const nuxt4 = modules.filter(module => moduleSupportsNuxt(module.compatibility?.nuxt, 4))
+    expect(modules.length).toBeGreaterThan(100)
+    expect(nuxt4.length).toBeGreaterThan(50)
+  })
+})
+
+describe('moduleSupportsNuxt', () => {
+  it('matches caret ranges for a single major', () => {
+    expect(moduleSupportsNuxt('^3.0.0', 3)).toBe(true)
+    expect(moduleSupportsNuxt('^3.0.0', 4)).toBe(false)
+    expect(moduleSupportsNuxt('^4.0.0', 3)).toBe(false)
+    expect(moduleSupportsNuxt('^4.0.0', 4)).toBe(true)
+  })
+
+  it('treats >=3.0.0 as compatible with Nuxt 3 and 4', () => {
+    expect(moduleSupportsNuxt('>=3.0.0', 3)).toBe(true)
+    expect(moduleSupportsNuxt('>=3.0.0', 4)).toBe(true)
+  })
+
+  it('handles union ranges', () => {
+    const range = '^3.15.0 || ^4.0.0'
+    expect(moduleSupportsNuxt(range, 3)).toBe(true)
+    expect(moduleSupportsNuxt(range, 4)).toBe(true)
+  })
+
+  it('returns false for empty or invalid ranges', () => {
+    expect(moduleSupportsNuxt(undefined, 3)).toBe(false)
+    expect(moduleSupportsNuxt('', 3)).toBe(false)
+    expect(moduleSupportsNuxt('not-a-range', 3)).toBe(false)
+  })
+})
+
+describe('getModuleNuxtMajors', () => {
+  it('returns badge majors for common ranges', () => {
+    expect(getModuleNuxtMajors('^3.0.0')).toEqual([3])
+    expect(getModuleNuxtMajors('^4.0.0')).toEqual([4])
+    expect(getModuleNuxtMajors('>=3.0.0')).toEqual([3, 4])
+    expect(getModuleNuxtMajors('^3.15.0 || ^4.0.0')).toEqual([3, 4])
+  })
+})
diff --git a/test/unit/modules-query.spec.ts b/test/unit/modules-query.spec.ts
new file mode 100644
index 000000000..84da26128
--- /dev/null
+++ b/test/unit/modules-query.spec.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { modulesCacheKey, normalizeModulesQuery } from '../../shared/utils/modules-query'
+
+describe('normalizeModulesQuery', () => {
+  it('accepts string version values', () => {
+    expect(normalizeModulesQuery({ version: '4' }).version).toBe('4')
+    expect(normalizeModulesQuery({ version: '3' }).version).toBe('3')
+    expect(normalizeModulesQuery({ version: 'all' }).version).toBe('all')
+  })
+
+  it('coerces numeric version values from h3 query parsing', () => {
+    expect(normalizeModulesQuery({ version: 4 }).version).toBe('4')
+    expect(normalizeModulesQuery({ version: 3 }).version).toBe('3')
+  })
+
+  it('defaults missing version to 3', () => {
+    expect(normalizeModulesQuery({}).version).toBe('3')
+    expect(normalizeModulesQuery({ version: '' }).version).toBe('3')
+    expect(normalizeModulesQuery({ version: null }).version).toBe('3')
+  })
+})
+
+describe('modulesCacheKey', () => {
+  it('stringifies numeric version in the cache key', () => {
+    expect(modulesCacheKey({ version: 4 })).toBe('4-all')
+    expect(modulesCacheKey({ version: '4', category: 'UI' })).toBe('4-UI')
+  })
+})

From 9c993ae52540d4cf69e9931f6468f22d6491721c Mon Sep 17 00:00:00 2001
From: Ivan Bochkarev <ivanx86@gmail.com>
Date: Mon, 20 Jul 2026 15:23:11 +0600
Subject: [PATCH 2/3] docs(modules): document Nuxt version filter and badges

---
 content/modules.yml                      |  2 +-
 server/mcp/tools/modules/get-module.ts   |  6 ++++--
 server/mcp/tools/modules/list-modules.ts | 21 ++++++++++++++++-----
 server/routes/raw/modules.md.get.ts      |  9 +++++++++
 4 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/content/modules.yml b/content/modules.yml
index 2a07c4f64..ebfe919a1 100644
--- a/content/modules.yml
+++ b/content/modules.yml
@@ -1,6 +1,6 @@
 title: Nuxt Modules
 navigation.title: Modules
-description: 'Discover our list of modules to supercharge your Nuxt project. Created by the Nuxt team and community.'
+description: 'Discover Nuxt modules for your project. Filter by Nuxt 3 or Nuxt 4. Each card shows version badges from the module''s declared compatibility.nuxt range.'
 navigation.icon: i-lucide-package
 links:
   - label: 'Create a Nuxt module'
diff --git a/server/mcp/tools/modules/get-module.ts b/server/mcp/tools/modules/get-module.ts
index 59ef7ea33..889a99cc2 100644
--- a/server/mcp/tools/modules/get-module.ts
+++ b/server/mcp/tools/modules/get-module.ts
@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { Module } from '#shared/types'
+import { getModuleNuxtMajors } from '#shared/utils/modules'
 
 export default defineMcpTool({
   description: `Retrieves complete details about a specific Nuxt module including README, compatibility, maintainers, and stats.
@@ -8,9 +9,9 @@ WHEN TO USE: Use this tool when you know the EXACT module identifier. Common sce
 - User asks for a specific module: "Get details about @nuxt/ui"
 - User mentions a known module: "Show me nuxt-icon module"
 - You found a relevant module from list_modules and want full details
-- You need to check Nuxt 4 compatibility for a specific module
+- You need to check Nuxt 4 compatibility for a specific module (see compatibility.nuxt and nuxtMajors)
 
-WHEN NOT TO USE: If you don't know the exact module identifier and need to search/discover modules, use list_modules first.
+WHEN NOT TO USE: If you don't know the exact module identifier and need to search/discover modules, use list_modules first (pass version "4" to filter the catalog).
 
 PARAMETER: slug (required) - The unique module identifier
 EXAMPLES:
@@ -63,6 +64,7 @@ EXAMPLES:
       category: module.category,
       type: module.type,
       compatibility: module.compatibility,
+      nuxtMajors: getModuleNuxtMajors(module.compatibility?.nuxt),
       stats: module.stats ? { downloads: module.stats.downloads, stars: module.stats.stars } : undefined,
       readme,
       url: `https://nuxt.com/modules/${module.name}`
diff --git a/server/mcp/tools/modules/list-modules.ts b/server/mcp/tools/modules/list-modules.ts
index 573ea7546..c4057e2aa 100644
--- a/server/mcp/tools/modules/list-modules.ts
+++ b/server/mcp/tools/modules/list-modules.ts
@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { Module, Stats } from '#shared/types'
+import { getModuleNuxtMajors, moduleSupportsNuxt } from '#shared/utils/modules'
 
 export default defineMcpTool({
   description: `Lists all available Nuxt modules with optional filtering and sorting capabilities.
@@ -9,20 +10,23 @@ WHEN TO USE: Use this tool when you need to DISCOVER or SEARCH for modules. Comm
 - "What UI libraries are available?" - filter by category
 - "Show me popular image optimization modules" - filter + sort by downloads
 - "Find a module for X feature" - general exploration
+- "Modules compatible with Nuxt 4" - set version to "4"
 
 PARAMETERS:
 - search: Filter by name, description, or npm package name
 - category: Filter by exact category name (e.g., "Security", "UI", "Database", "CMS", "SEO") — use search for keyword discovery, not category
+- version: Filter by declared Nuxt major via compatibility.nuxt ("3", "4", or "all"). Default "3" matches the modules catalog on nuxt.com.
 - sort: Order by downloads, stars, publishedAt, or createdAt
 - order: asc or desc
 - includeStats: Include full per-module stats (downloads, stars, publishedAt, createdAt, etc.). Defaults to true when sort is publishedAt or createdAt.
 
 WHEN NOT TO USE: If you already know the exact module slug (e.g., "@nuxt/ui"), use get_module directly.
 
-OUTPUT: Returns list of modules with name, description, category, and either downloads/stars or full stats. Use get_module for complete details including README and compatibility.`,
+OUTPUT: Returns list of modules with name, description, category, nuxtMajors (3 and/or 4 from compatibility.nuxt), and either downloads/stars or full stats. Use get_module for complete details including README and compatibility.`,
   inputSchema: {
     search: z.string().optional().describe('Search term to filter modules by name, description, or npm package name'),
     category: z.string().optional().describe('Filter by exact category name (e.g., "Security", "UI", "Database", "CMS", "SEO"). Auth modules use category "Security", not "auth". Prefer search for keyword discovery.'),
+    version: z.enum(['3', '4', 'all']).optional().default('3').describe('Filter by Nuxt major declared in compatibility.nuxt. Use "all" to skip major filtering.'),
     sort: z.enum(['downloads', 'stars', 'publishedAt', 'createdAt']).optional().default('downloads').describe('Sort modules by downloads, stars, published date, or created date'),
     order: z.enum(['asc', 'desc']).optional().default('desc').describe('Sort order (ascending or descending)'),
     includeStats: z.boolean().optional().describe('Include full per-module stats. Defaults to true when sort is publishedAt or createdAt.')
@@ -34,19 +38,25 @@ OUTPUT: Returns list of modules with name, description, category, and either dow
   inputExamples: [
     { search: 'auth' },
     { category: 'ui', sort: 'downloads' },
-    { search: 'image', sort: 'stars', order: 'desc' }
+    { search: 'image', sort: 'stars', order: 'desc' },
+    { version: '4', category: 'UI' }
   ],
   cache: {
     maxAge: '1h',
-    getKey: (args: { search?: string, category?: string, sort?: string, order?: string, includeStats?: boolean }) =>
-      `search=${args.search ?? ''}|category=${args.category ?? ''}|sort=${args.sort ?? 'downloads'}|order=${args.order ?? 'desc'}|stats=${args.includeStats ?? (args.sort === 'publishedAt' || args.sort === 'createdAt')}`
+    getKey: (args: { search?: string, category?: string, version?: string, sort?: string, order?: string, includeStats?: boolean }) =>
+      `search=${args.search ?? ''}|category=${args.category ?? ''}|version=${args.version ?? '3'}|sort=${args.sort ?? 'downloads'}|order=${args.order ?? 'desc'}|stats=${args.includeStats ?? (args.sort === 'publishedAt' || args.sort === 'createdAt')}`
   },
-  async handler({ search, category, sort = 'downloads', order = 'desc', includeStats }) {
+  async handler({ search, category, version = '3', sort = 'downloads', order = 'desc', includeStats }) {
     const withStats = includeStats ?? (sort === 'publishedAt' || sort === 'createdAt')
     const response = await $fetch<{ modules: Module[], stats: Stats }>('https://api.nuxt.com/modules')
 
     let modules = response.modules || []
 
+    if (version !== 'all') {
+      const major = Number(version) as 3 | 4
+      modules = modules.filter(module => moduleSupportsNuxt(module.compatibility?.nuxt, major))
+    }
+
     if (category) {
       modules = modules.filter(module => module.category === category)
     }
@@ -114,6 +124,7 @@ OUTPUT: Returns list of modules with name, description, category, and either dow
           website: module.website,
           learn_more: module.learn_more,
           category: module.category,
+          nuxtMajors: getModuleNuxtMajors(module.compatibility?.nuxt),
           url: `https://nuxt.com/modules/${module.name}`
         }
 
diff --git a/server/routes/raw/modules.md.get.ts b/server/routes/raw/modules.md.get.ts
index 4e00e705f..a80b164a2 100644
--- a/server/routes/raw/modules.md.get.ts
+++ b/server/routes/raw/modules.md.get.ts
@@ -1,3 +1,5 @@
+import { getModuleNuxtMajors } from '#shared/utils/modules'
+
 export default defineCachedEventHandler(async (event) => {
   const domain = getSiteUrl(event)
   const modules = await fetchModules(event) || []
@@ -6,6 +8,9 @@ export default defineCachedEventHandler(async (event) => {
     '# Nuxt Modules',
     '',
     `> ${modules.length}+ modules to supercharge your [Nuxt](https://nuxt.com) project.`,
+    '',
+    'On the [modules catalog](https://nuxt.com/modules), filter by Nuxt major with `?version=3`, `?version=4`, or `?version=all` (default is Nuxt 3).',
+    'Each card shows Nuxt 3 / Nuxt 4 badges derived from the module\'s `compatibility.nuxt` semver range in the [nuxt/modules](https://github.com/nuxt/modules) registry.',
     ''
   ]
 
@@ -19,6 +24,7 @@ export default defineCachedEventHandler(async (event) => {
   for (const [category, mods] of categories) {
     lines.push(`## ${category}`, '')
     for (const mod of mods) {
+      const majors = getModuleNuxtMajors(mod.compatibility?.nuxt)
       const links = [
         mod.website ? `[Docs](${mod.website})` : '',
         mod.repo ? `[GitHub](https://github.com/${mod.repo})` : '',
@@ -27,6 +33,9 @@ export default defineCachedEventHandler(async (event) => {
 
       lines.push(`### ${mod.npm}`, '')
       lines.push(mod.description, '')
+      if (majors.length) {
+        lines.push(`Nuxt: ${majors.map(major => String(major)).join(', ')}`, '')
+      }
       lines.push(`Install: \`npx nuxt@latest module add ${mod.name}\``, '')
       lines.push(links, '')
     }

From ef47be38d610c9e1fb6dac621b020c6fdaf91791 Mon Sep 17 00:00:00 2001
From: Ivan Bochkarev <ivanx86@gmail.com>
Date: Mon, 20 Jul 2026 16:32:46 +0600
Subject: [PATCH 3/3] fix(modules): address review feedback for query
 validation and tests

---
 app/pages/modules/index.vue             |  2 +-
 server/api/v1/modules/index.get.ts      |  4 +++-
 test/unit/modules-compatibility.spec.ts | 26 +++++++++++++++++++------
 3 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/app/pages/modules/index.vue b/app/pages/modules/index.vue
index ade7e52c3..e3b96c0b9 100644
--- a/app/pages/modules/index.vue
+++ b/app/pages/modules/index.vue
@@ -152,7 +152,7 @@ const clearAllModules = () => {
       }"
     >
       <template #title>
-        Build faster with <span class="text-primary">{{ filteredModules.length }}+</span> Nuxt Modules
+        Build faster with <span class="text-primary">{{ filteredModules.length }}</span> Nuxt Modules
       </template>
 
       <template #description>
diff --git a/server/api/v1/modules/index.get.ts b/server/api/v1/modules/index.get.ts
index f514b052d..f492c43b8 100644
--- a/server/api/v1/modules/index.get.ts
+++ b/server/api/v1/modules/index.get.ts
@@ -2,7 +2,9 @@ import { moduleSupportsNuxt } from '#shared/utils/modules'
 import { modulesCacheKey, normalizeModulesQuery } from '#shared/utils/modules-query'
 
 export default defineCachedEventHandler(async (event) => {
-  const { version, category } = normalizeModulesQuery(getQuery(event) as Record<string, unknown>)
+  const { version, category } = await getValidatedQuery(event, query =>
+    normalizeModulesQuery(query as Record<string, unknown>)
+  )
   console.log(`Fetching v${version} modules...${category ? ` for category: ${category}` : ''}`)
 
   let modules = await fetchModules(event) || []
diff --git a/test/unit/modules-compatibility.spec.ts b/test/unit/modules-compatibility.spec.ts
index 420c2a88e..66e0671c9 100644
--- a/test/unit/modules-compatibility.spec.ts
+++ b/test/unit/modules-compatibility.spec.ts
@@ -1,13 +1,27 @@
 import { describe, expect, it } from 'vitest'
 import { getModuleNuxtMajors, moduleSupportsNuxt } from '../../shared/utils/modules'
 
-describe('moduleSupportsNuxt against CDN registry', () => {
-  it('finds Nuxt 4 compatible modules in the live modules.json', async () => {
-    const modules = await fetch('https://unpkg.com/@nuxt/modules@latest/modules.json')
-      .then(res => res.json()) as Array<{ name: string, compatibility?: { nuxt?: string } }>
+/** Deterministic stand-in for modules.json compatibility cases (no network). */
+const registryFixture = [
+  { name: 'only-nuxt3', compatibility: { nuxt: '^3.0.0' } },
+  { name: 'only-nuxt4', compatibility: { nuxt: '^4.0.0' } },
+  { name: 'nuxt3-and-4', compatibility: { nuxt: '^3.15.0 || ^4.0.0' } },
+  { name: 'nuxt-gte-3', compatibility: { nuxt: '>=3.0.0' } },
+  { name: 'nuxt2-only', compatibility: { nuxt: '^2.0.0' } },
+  { name: 'missing-range', compatibility: {} },
+  // Pad so the suite still asserts a registry-sized catalog (>100 modules).
+  ...Array.from({ length: 100 }, (_, i) => ({
+    name: `fixture-module-${i}`,
+    compatibility: { nuxt: i % 2 === 0 ? '^3.0.0 || ^4.0.0' : '^3.0.0' }
+  }))
+]
 
-    const nuxt4 = modules.filter(module => moduleSupportsNuxt(module.compatibility?.nuxt, 4))
-    expect(modules.length).toBeGreaterThan(100)
+describe('moduleSupportsNuxt against modules registry fixture', () => {
+  it('finds Nuxt 4 compatible modules without network access', () => {
+    const nuxt4 = registryFixture.filter(module =>
+      moduleSupportsNuxt(module.compatibility?.nuxt, 4)
+    )
+    expect(registryFixture.length).toBeGreaterThan(100)
     expect(nuxt4.length).toBeGreaterThan(50)
   })
 })