merge main

Author: whitep4nth3r

.github/workflows/ci.yml

@@ -150,7 +150,9 @@ jobs:
         run: pnpm install
 
       - name: 🏗️ Build project
-        run: pnpm build:playwright
+        run: pnpm build:test
+        env:
+          VALIDATE_HTML: true
 
       - name: 🖥️ Test project (browser)
         run: pnpm test:browser:prebuilt
@@ -178,7 +180,7 @@ jobs:
         run: pnpm install
 
       - name: 🏗️ Build project
-        run: NODE_ENV=test pnpm build
+        run: pnpm build:test
 
       - name: ♿ Accessibility audit (Lighthouse - ${{ matrix.mode }} mode)
         run: ./scripts/lighthouse-a11y.sh
@@ -210,3 +212,25 @@ jobs:
 
       - name: 🧹 Check for unused production code
         run: pnpm knip --production
+
+  i18n:
+    name: 🌐 i18n validation
+    runs-on: ubuntu-24.04-arm
+
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: lts/*
+
+      - uses: pnpm/action-setup@1e1c8eafbd745f64b1ef30a7d7ed7965034c486c # 1e1c8eafbd745f64b1ef30a7d7ed7965034c486c
+        name: 🟧 Install pnpm
+        with:
+          cache: true
+
+      - name: 📦 Install dependencies (root only, no scripts)
+        run: pnpm install --filter . --ignore-scripts
+
+      - name: 🌐 Check for missing or dynamic i18n keys
+        run: pnpm i18n:report

.github/workflows/welcome.yml

@@ -0,0 +1,52 @@
+name: welcome
+
+on:
+  pull_request_target:
+    types:
+      - closed
+
+permissions: {}
+
+jobs:
+  welcome:
+    permissions:
+      pull-requests: write # to comment on PRs
+    if: github.repository == 'npmx-dev/npmx.dev' && github.event.pull_request.merged == true
+    runs-on: ubuntu-slim
+    name: 🎉 Welcome new contributor
+    steps:
+      - name: 🎉 Welcome new contributor
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const author = pr.user.login;
+
+            // Check if this is the author's first merged PR
+            const { data: prs } = await github.rest.search.issuesAndPullRequests({
+              q: `repo:${context.repo.owner}/${context.repo.repo} type:pr is:merged author:${author}`,
+            });
+
+            // If the only merged PR is this one, it's their first contribution
+            if (prs.total_count !== 1) {
+              console.log(`@${author} already has ${prs.total_count} merged PRs — skipping welcome comment.`);
+              return;
+            }
+
+            const emojis = ['🎉', '🥳', '🎊', '🚀', '⭐', '💫', '✨', '💪', '👏', '🙌', '🤩', '💥'];
+            const emoji = emojis[Math.floor(Math.random() * emojis.length)];
+
+            const body = [
+              `Thanks for your first contribution, @${author}! ${emoji}`,
+              '',
+              `We'd love to welcome you to the npmx community. Come and say hi on [Discord](https://chat.npmx.dev)! And once you've joined, visit [npmx.wamellow.com](https://npmx.wamellow.com/) to claim the **contributor** role.`,
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+              body,
+            });
+
+            console.log(`Welcomed new contributor @${author} on PR #${pr.number}`);

.gitignore

@@ -39,3 +39,6 @@ test-results/
 
 # generated files
 shared/types/lexicons
+
+# output
+.vercel

CONTRIBUTING.md

@@ -39,6 +39,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Import order](#import-order)
   - [Naming conventions](#naming-conventions)
   - [Vue components](#vue-components)
+  - [Internal linking](#internal-linking)
 - [RTL Support](#rtl-support)
 - [Localization (i18n)](#localization-i18n)
   - [Approach](#approach)
@@ -278,6 +279,79 @@ const props = defineProps<{
 
 Ideally, extract utilities into separate files so they can be unit tested. 🙏
 
+### Internal linking
+
+Always use **object syntax with named routes** for internal navigation. This makes links resilient to URL structure changes and provides type safety via `unplugin-vue-router`.
+
+```vue
+<!-- Good: named route -->
+<NuxtLink :to="{ name: 'settings' }">Settings</NuxtLink>
+
+<!-- Bad: string path -->
+<NuxtLink to="/settings">Settings</NuxtLink>
+```
+
+The same applies to programmatic navigation:
+
+```typescript
+// Good
+navigateTo({ name: 'compare' })
+router.push({ name: 'search' })
+
+// Bad
+navigateTo('/compare')
+router.push('/search')
+```
+
+For routes with parameters, pass them explicitly:
+
+```vue
+<NuxtLink :to="{ name: '~username', params: { username } }">Profile</NuxtLink>
+<NuxtLink :to="{ name: 'org', params: { org: orgName } }">Organization</NuxtLink>
+```
+
+Query parameters work as expected:
+
+```vue
+<NuxtLink :to="{ name: 'compare', query: { packages: pkg.name } }">Compare</NuxtLink>
+```
+
+#### Package routes
+
+For package links, use the auto-imported `packageRoute()` utility from `app/utils/router.ts`. It handles scoped/unscoped packages and optional versions:
+
+```vue
+<!-- Links to /package/vue -->
+<NuxtLink :to="packageRoute('vue')">vue</NuxtLink>
+
+<!-- Links to /package/@nuxt/kit -->
+<NuxtLink :to="packageRoute('@nuxt/kit')">@nuxt/kit</NuxtLink>
+
+<!-- Links to /package/vue/v/3.5.0 -->
+<NuxtLink :to="packageRoute('vue', '3.5.0')">vue@3.5.0</NuxtLink>
+```
+
+> [!IMPORTANT]
+> Never construct package URLs as strings. The route structure uses separate `org` and `name` params, and `packageRoute()` handles the splitting correctly.
+
+#### Available route names
+
+| Route name        | URL pattern                       | Parameters                |
+| ----------------- | --------------------------------- | ------------------------- |
+| `index`           | `/`                               | &mdash;                   |
+| `about`           | `/about`                          | &mdash;                   |
+| `compare`         | `/compare`                        | &mdash;                   |
+| `privacy`         | `/privacy`                        | &mdash;                   |
+| `search`          | `/search`                         | &mdash;                   |
+| `settings`        | `/settings`                       | &mdash;                   |
+| `package`         | `/package/:org?/:name`            | `org?`, `name`            |
+| `package-version` | `/package/:org?/:name/v/:version` | `org?`, `name`, `version` |
+| `code`            | `/package-code/:path+`            | `path` (array)            |
+| `docs`            | `/package-docs/:path+`            | `path` (array)            |
+| `org`             | `/org/:org`                       | `org`                     |
+| `~username`       | `/~:username`                     | `username`                |
+| `~username-orgs`  | `/~:username/orgs`                | `username`                |
+
 ## RTL Support
 
 We support `right-to-left` languages, we need to make sure that the UI is working correctly in both directions.
@@ -334,7 +408,7 @@ To add a new locale:
    cp i18n/locales/uk-UA.json lunaria/files/uk-UA.json
    ```
 
-   > [!IMPORTANT]
+   > ⚠**Important:**
    > This file must be committed. Lunaria uses git history to track translation progress, so the build will fail if this file is missing.
 
 5. If the language is `right-to-left`, add `dir: 'rtl'` (see `ar-EG` in config for example)

app/app.vue

@@ -62,7 +62,7 @@ onKeyDown(
       return
     }
 
-    router.push('/search')
+    router.push({ name: 'search' })
   },
   { dedupe: true },
 )

app/components/AppFooter.vue

@@ -15,17 +15,17 @@ const isHome = computed(() => route.name === 'index')
         </div>
         <!-- Desktop: Show all links. Mobile: Links are in MobileMenu -->
         <div class="hidden sm:flex items-center gap-6">
-          <NuxtLink to="/about" class="link-subtle font-mono text-xs flex items-center">
+          <NuxtLink :to="{ name: 'about' }" class="link-subtle font-mono text-xs flex items-center">
             {{ $t('footer.about') }}
           </NuxtLink>
           <NuxtLink
-            to="/blog"
+            :to="{ name: 'blog' }"
             class="link-subtle font-mono text-xs min-h-8 sm:min-h-11 flex items-center"
           >
             {{ $t('footer.blog') }}
           </NuxtLink>
           <NuxtLink
-            to="/privacy"
+            :to="{ name: 'privacy' }"
             class="link-subtle font-mono text-xs min-h-11 flex items-center gap-1 lowercase"
           >
             {{ $t('privacy_policy.title') }}

app/components/AppHeader.vue

@@ -65,7 +65,7 @@ onKeyStroke(
   e => isKeyWithoutModifiers(e, ',') && !isEditableElement(e.target),
   e => {
     e.preventDefault()
-    navigateTo('/settings')
+    navigateTo({ name: 'settings' })
   },
   { dedupe: true },
 )
@@ -78,7 +78,7 @@ onKeyStroke(
     !e.defaultPrevented,
   e => {
     e.preventDefault()
-    navigateTo('/compare')
+    navigateTo({ name: 'compare' })
   },
   { dedupe: true },
 )
@@ -106,7 +106,7 @@ onKeyStroke(
       <!-- Desktop: Logo (navigates home) -->
       <div v-if="showLogo" class="hidden sm:flex flex-shrink-0 items-center">
         <NuxtLink
-          to="/"
+          :to="{ name: 'index' }"
           :aria-label="$t('header.home')"
           dir="ltr"
           class="inline-flex items-center gap-1 header-logo font-mono text-lg font-medium text-fg hover:text-fg/90 transition-colors duration-200 rounded"
@@ -152,7 +152,7 @@ onKeyStroke(
       <div class="flex-shrink-0 flex items-center gap-0.5 sm:gap-2">
         <!-- Desktop: Compare link -->
         <NuxtLink
-          to="/compare"
+          :to="{ name: 'compare' }"
           class="hidden sm:inline-flex link-subtle font-mono text-sm items-center gap-2 px-2 py-1.5 hover:bg-bg-subtle focus-visible:outline-accent/70 rounded"
           aria-keyshortcuts="c"
         >
@@ -167,7 +167,7 @@ onKeyStroke(
 
         <!-- Desktop: Settings link -->
         <NuxtLink
-          to="/settings"
+          :to="{ name: 'settings' }"
           class="hidden sm:inline-flex link-subtle font-mono text-sm items-center gap-2 px-2 py-1.5 hover:bg-bg-subtle focus-visible:outline-accent/70 rounded"
           aria-keyshortcuts=","
         >

app/components/Code/DirectoryListing.vue

@@ -1,12 +1,15 @@
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
+import type { RouteLocationRaw } from 'vue-router'
 import { getFileIcon } from '~/utils/file-icons'
 import { formatBytes } from '~/utils/formatters'
 
 const props = defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
+  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
+  basePath: string[]
 }>()
 
 // Get the current directory's contents
@@ -36,6 +39,18 @@ const parentPath = computed(() => {
   if (parts.length <= 1) return ''
   return parts.slice(0, -1).join('/')
 })
+
+// Build route object for a path
+function getCodeRoute(nodePath?: string): RouteLocationRaw {
+  if (!nodePath) {
+    return { name: 'code', params: { path: props.basePath as [string, ...string[]] } }
+  }
+  const pathSegments = [...props.basePath, ...nodePath.split('/')]
+  return {
+    name: 'code',
+    params: { path: pathSegments as [string, ...string[]] },
+  }
+}
 </script>
 
 <template>
@@ -61,7 +76,7 @@ const parentPath = computed(() => {
         >
           <td class="py-2 px-4">
             <NuxtLink
-              :to="parentPath ? `${baseUrl}/${parentPath}` : baseUrl"
+              :to="getCodeRoute(parentPath || undefined)"
               class="flex items-center gap-2 font-mono text-sm text-fg-muted hover:text-fg transition-colors"
             >
               <span class="i-carbon:folder w-4 h-4 text-yellow-600" />
@@ -79,7 +94,7 @@ const parentPath = computed(() => {
         >
           <td class="py-2 px-4">
             <NuxtLink
-              :to="`${baseUrl}/${node.path}`"
+              :to="getCodeRoute(node.path)"
               class="flex items-center gap-2 font-mono text-sm hover:text-fg transition-colors"
               :class="node.type === 'directory' ? 'text-fg' : 'text-fg-muted'"
             >

app/components/Code/FileTree.vue

@@ -1,11 +1,14 @@
 <script setup lang="ts">
 import type { PackageFileTree } from '#shared/types'
+import type { RouteLocationRaw } from 'vue-router'
 import { getFileIcon } from '~/utils/file-icons'
 
 const props = defineProps<{
   tree: PackageFileTree[]
   currentPath: string
   baseUrl: string
+  /** Base path segments for the code route (e.g., ['nuxt', 'v', '4.2.0']) */
+  basePath: string[]
   depth?: number
 }>()
 
@@ -18,6 +21,15 @@ function isNodeActive(node: PackageFileTree): boolean {
   return false
 }
 
+// Build route object for a file path
+function getFileRoute(nodePath: string): RouteLocationRaw {
+  const pathSegments = [...props.basePath, ...nodePath.split('/')]
+  return {
+    name: 'code',
+    params: { path: pathSegments as [string, ...string[]] },
+  }
+}
+
 const { toggleDir, isExpanded, autoExpandAncestors } = useFileTreeState(props.baseUrl)
 
 // Auto-expand directories in the current path
@@ -63,14 +75,15 @@ watch(
           :tree="node.children"
           :current-path="currentPath"
           :base-url="baseUrl"
+          :base-path="basePath"
           :depth="depth + 1"
         />
       </template>
 
       <!-- File -->
       <template v-else>
         <NuxtLink
-          :to="`${baseUrl}/${node.path}`"
+          :to="getFileRoute(node.path)"
           class="flex items-center gap-1.5 py-1.5 px-3 font-mono text-sm transition-colors hover:bg-bg-muted"
           :class="currentPath === node.path ? 'bg-bg-muted text-fg' : 'text-fg-muted'"
           :style="{ paddingLeft: `${depth * 12 + 32}px` }"