forked from
npmx.dev/npmx.dev
[READ-ONLY]
a fast, modern browser for the npm registry
docs: document new object-syntax links
+74
+74
CONTRIBUTING.md
+74
CONTRIBUTING.md
···
39
39
- [Import order](#import-order)
40
40
- [Naming conventions](#naming-conventions)
41
41
- [Vue components](#vue-components)
42
+
- [Internal linking](#internal-linking)
42
43
- [RTL Support](#rtl-support)
43
44
- [Localization (i18n)](#localization-i18n)
44
45
- [Approach](#approach)
···
277
278
```
278
279
279
280
Ideally, extract utilities into separate files so they can be unit tested. 🙏
281
+
282
+
### Internal linking
283
+
284
+
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`.
285
+
286
+
```vue
287
+
<!-- Good: named route -->
288
+
<NuxtLink :to="{ name: 'settings' }">Settings</NuxtLink>
289
+
290
+
<!-- Bad: string path -->
291
+
<NuxtLink to="/settings">Settings</NuxtLink>
292
+
```
293
+
294
+
The same applies to programmatic navigation:
295
+
296
+
```typescript
297
+
// Good
298
+
navigateTo({ name: 'compare' })
299
+
router.push({ name: 'search' })
300
+
301
+
// Bad
302
+
navigateTo('/compare')
303
+
router.push('/search')
304
+
```
305
+
306
+
For routes with parameters, pass them explicitly:
307
+
308
+
```vue
309
+
<NuxtLink :to="{ name: '~username', params: { username } }">Profile</NuxtLink>
310
+
<NuxtLink :to="{ name: 'org', params: { org: orgName } }">Organization</NuxtLink>
311
+
```
312
+
313
+
Query parameters work as expected:
314
+
315
+
```vue
316
+
<NuxtLink :to="{ name: 'compare', query: { packages: pkg.name } }">Compare</NuxtLink>
317
+
```
318
+
319
+
#### Package routes
320
+
321
+
For package links, use the auto-imported `packageRoute()` utility from `app/utils/router.ts`. It handles scoped/unscoped packages and optional versions:
322
+
323
+
```vue
324
+
<!-- Links to /package/vue -->
325
+
<NuxtLink :to="packageRoute('vue')">vue</NuxtLink>
326
+
327
+
<!-- Links to /package/@nuxt/kit -->
328
+
<NuxtLink :to="packageRoute('@nuxt/kit')">@nuxt/kit</NuxtLink>
329
+
330
+
<!-- Links to /package/vue/v/3.5.0 -->
331
+
<NuxtLink :to="packageRoute('vue', '3.5.0')">vue@3.5.0</NuxtLink>
332
+
```
333
+
334
+
> [!IMPORTANT]
335
+
> Never construct package URLs as strings. The route structure uses separate `org` and `name` params, and `packageRoute()` handles the splitting correctly.
336
+
337
+
#### Available route names
338
+
339
+
| Route name | URL pattern | Parameters |
340
+
| ----------------- | --------------------------------- | ------------------------- |
341
+
| `index` | `/` | — |
342
+
| `about` | `/about` | — |
343
+
| `compare` | `/compare` | — |
344
+
| `privacy` | `/privacy` | — |
345
+
| `search` | `/search` | — |
346
+
| `settings` | `/settings` | — |
347
+
| `package` | `/package/:org?/:name` | `org?`, `name` |
348
+
| `package-version` | `/package/:org?/:name/v/:version` | `org?`, `name`, `version` |
349
+
| `code` | `/package-code/:path+` | `path` (array) |
350
+
| `docs` | `/package-docs/:path+` | `path` (array) |
351
+
| `org` | `/org/:org` | `org` |
352
+
| `~username` | `/~:username` | `username` |
353
+
| `~username-orgs` | `/~:username/orgs` | `username` |
280
354
281
355
## RTL Support
282
356