Merge branch 'main' into main

Author: graphieros

.github/workflows/ci.yml

@@ -117,7 +117,7 @@ jobs:
         run: pnpm install
 
       - name: 🏗️ Build project
-        run: pnpm build
+        run: NODE_ENV=test pnpm build
 
       - name: ♿ Accessibility audit (Lighthouse - ${{ matrix.mode }} mode)
         run: ./scripts/lighthouse-a11y.sh

CONTRIBUTING.md

@@ -42,6 +42,7 @@ We want to create 'a fast, modern browser for the npm registry.' This means, amo
   - [Unit tests](#unit-tests)
   - [Component accessibility tests](#component-accessibility-tests)
   - [End to end tests](#end-to-end-tests)
+  - [Test fixtures (mocking external APIs)](#test-fixtures-mocking-external-apis)
 - [Submitting changes](#submitting-changes)
   - [Before submitting](#before-submitting)
   - [Pull request process](#pull-request-process)
@@ -482,6 +483,69 @@ pnpm test:browser:ui     # Run with Playwright UI
 
 Make sure to read about [Playwright best practices](https://playwright.dev/docs/best-practices) and don't rely on classes/IDs but try to follow user-replicable behaviour (like selecting an element based on text content instead).
 
+### Test fixtures (mocking external APIs)
+
+E2E tests use a fixture system to mock external API requests, ensuring tests are deterministic and don't hit real APIs. This is handled at two levels:
+
+**Server-side mocking** (`modules/fixtures.ts` + `modules/runtime/server/cache.ts`):
+
+- Intercepts all `$fetch` calls during SSR
+- Serves pre-recorded fixture data from `test/fixtures/`
+- Enabled via `NUXT_TEST_FIXTURES=true` or Nuxt test mode
+
+**Client-side mocking** (`test/e2e/test-utils.ts`):
+
+- Uses Playwright's route interception to mock browser requests
+- All test files import from `./test-utils` instead of `@nuxt/test-utils/playwright`
+- Throws a clear error if an unmocked external request is detected
+
+#### Fixture files
+
+Fixtures are stored in `test/fixtures/` with this structure:
+
+```
+test/fixtures/
+├── npm-registry/
+│   ├── packuments/       # Package metadata (vue.json, @nuxt/kit.json)
+│   ├── search/           # Search results (vue.json, nuxt.json)
+│   └── orgs/             # Org package lists (nuxt.json)
+├── npm-api/
+│   └── downloads/        # Download stats
+└── users/                # User package lists
+```
+
+#### Adding new fixtures
+
+1. **Generate fixtures** using the script:
+
+   ```bash
+   pnpm generate:fixtures vue lodash @nuxt/kit
+   ```
+
+2. **Or manually create** a JSON file in the appropriate directory
+
+#### Environment variables
+
+| Variable                          | Purpose                            |
+| --------------------------------- | ---------------------------------- |
+| `NUXT_TEST_FIXTURES=true`         | Enable server-side fixture mocking |
+| `NUXT_TEST_FIXTURES_VERBOSE=true` | Enable detailed fixture logging    |
+
+#### When tests fail due to missing fixtures
+
+If a test fails with an error like:
+
+```
+UNMOCKED EXTERNAL API REQUEST DETECTED
+API:  npm registry
+URL:  https://registry.npmjs.org/some-package
+```
+
+You need to either:
+
+1. Add a fixture file for that package/endpoint
+2. Update the mock handlers in `test/e2e/test-utils.ts` (client) or `modules/runtime/server/cache.ts` (server)
+
 ## Submitting changes
 
 ### Before submitting

app/components/Header/ConnectorModal.vue

@@ -81,10 +81,8 @@ function handleDisconnect() {
     <form v-else class="space-y-4" @submit.prevent="handleConnect">
       <!-- Contributor-only notice -->
       <div class="p-3 bg-amber-500/10 border border-amber-500/30 rounded-lg">
-        <div class="space-y-2">
-          <span
-            class="inline-block px-2 py-0.5 text-xs font-bold uppercase tracking-wider bg-amber-500/20 text-amber-400 rounded"
-          >
+        <div>
+          <span class="inline-block text-xs font-bold uppercase tracking-wider text-fg rounded">
             {{ $t('connector.modal.contributor_badge') }}
           </span>
           <p class="text-sm text-fg-muted">
@@ -94,7 +92,7 @@ function handleDisconnect() {
                   href="https://github.com/npmx-dev/npmx.dev/blob/main/CONTRIBUTING.md#local-connector-cli"
                   target="_blank"
                   rel="noopener noreferrer"
-                  class="text-amber-400 hover:underline"
+                  class="text-blue-400 hover:underline"
                 >
                   {{ $t('connector.modal.contributor_link') }}
                 </a>
@@ -213,7 +211,7 @@ function handleDisconnect() {
         role="alert"
         class="p-3 text-sm text-red-400 bg-red-500/10 border border-red-500/20 rounded-md"
       >
-        <p class="font-mono text-sm text-fg font-bold">
+        <p class="inline-block text-xs font-bold uppercase tracking-wider text-fg rounded">
           {{ $t('connector.modal.warning') }}
         </p>
         <p class="text-sm text-fg-muted">

app/composables/useAtproto.ts

@@ -1,11 +1,9 @@
-import type { UserSession } from '#shared/schemas/userSession'
-
 export function useAtproto() {
   const {
     data: user,
     pending,
     clear,
-  } = useFetch<UserSession | null>('/api/auth/session', {
+  } = useFetch('/api/auth/session', {
     server: false,
     immediate: !import.meta.test,
   })

knip.json

@@ -0,0 +1,55 @@
+import type { KnipConfig } from 'knip'
+
+const config: KnipConfig = {
+  workspaces: {
+    '.': {
+      entry: [
+        'app/app.vue!',
+        'app/error.vue!',
+        'app/pages/**/*.vue!',
+        'app/components/**/*.vue!',
+        'app/composables/**/*.ts!',
+        'app/middleware/**/*.ts!',
+        'app/plugins/**/*.ts!',
+        'app/utils/**/*.ts!',
+        'server/**/*.ts!',
+        'modules/**/*.ts!',
+        'config/**/*.ts!',
+        'lunaria/**/*.ts!',
+        'shared/**/*.ts!',
+        'i18n/**/*.ts',
+        'lunaria.config.ts',
+        'pwa-assets.config.ts',
+        '.lighthouserc.cjs',
+        'lighthouse-setup.cjs',
+        'uno-preset-rtl.ts!',
+        'scripts/**/*.ts',
+      ],
+      project: ['**/*.{ts,vue,cjs,mjs}'],
+      ignore: ['test/fixtures/**'],
+      ignoreDependencies: [
+        '@iconify-json/*',
+        '@vercel/kv',
+        '@voidzero-dev/vite-plus-core',
+        'vite-plus!',
+        'h3',
+        /** Needs to be explicitly installed, even though it is not imported, to avoid type errors. */
+        'unplugin-vue-router',
+        'vite-plugin-pwa',
+
+        /** Some components import types from here, but installing it directly could lead to a version mismatch */
+        'vue-router',
+      ],
+      ignoreUnresolved: ['#components', '#oauth/config'],
+    },
+    'cli': {
+      project: ['src/**/*.ts!'],
+    },
+    'docs': {
+      entry: ['app/**/*.{ts,vue}'],
+      ignoreDependencies: ['docus', 'better-sqlite3', 'nuxt!'],
+    },
+  },
+}
+
+export default config

knip.ts

@@ -6,7 +6,6 @@
  * If not set, defaults to 'dark'.
  */
 
-/** @param {import('puppeteer').Browser} browser */
 module.exports = async function setup(browser, { url }) {
   const colorMode = process.env.LIGHTHOUSE_COLOR_MODE || 'dark'
   const page = await browser.newPage()

lighthouse-setup.cjs

@@ -27,16 +27,6 @@ export default defineNuxtModule({
         ...nitroConfig.storage[FETCH_CACHE_STORAGE_BASE],
         driver: 'vercel-runtime-cache',
       }
-
-      const env = process.env.VERCEL_ENV
-
-      nitroConfig.storage['oauth-atproto-state'] = {
-        driver: env === 'production' ? 'vercel-kv' : 'vercel-runtime-cache',
-      }
-
-      nitroConfig.storage['oauth-atproto-session'] = {
-        driver: env === 'production' ? 'vercel-kv' : 'vercel-runtime-cache',
-      }
     })
   },
 })

modules/cache.ts

@@ -0,0 +1,40 @@
+import process from 'node:process'
+import { addServerPlugin, createResolver, defineNuxtModule, useNuxt } from 'nuxt/kit'
+
+/**
+ * Test fixtures module for mocking external API requests.
+ *
+ * This module intercepts server-side requests to external APIs (npm registry, etc.)
+ * and serves pre-recorded fixture data instead. This ensures tests are deterministic
+ * and don't depend on external API availability.
+ *
+ * Enabled when:
+ * - `nuxt.options.test` is true (Nuxt test mode), OR
+ * - `NUXT_TEST_FIXTURES=true` environment variable is set
+ *
+ * Set `NUXT_TEST_FIXTURES_VERBOSE=true` for detailed logging.
+ *
+ * Note: This only mocks server-side requests. For client-side mocking in
+ * Playwright tests, see test/e2e/test-utils.ts.
+ */
+export default defineNuxtModule({
+  meta: {
+    name: 'fixtures',
+  },
+  setup() {
+    const nuxt = useNuxt()
+    const resolver = createResolver(import.meta.url)
+
+    if (nuxt.options.test || process.env.NUXT_TEST_FIXTURES === 'true') {
+      addServerPlugin(resolver.resolve('./runtime/server/cache.ts'))
+
+      nuxt.hook('nitro:config', nitroConfig => {
+        nitroConfig.storage ||= {}
+        nitroConfig.storage['fixtures'] = {
+          driver: 'fsLite',
+          base: resolver.resolve('../test/fixtures'),
+        }
+      })
+    }
+  },
+})