Merge branch 'main' into feat/concept-npm-requests

Author: 43081j

.env.example

@@ -1,2 +1,2 @@
-#secure password, can use openssl rand --hex 32
+#secure password, can use openssl rand -hex 32
 NUXT_SESSION_PASSWORD=""

.github/workflows/autofix.yml

@@ -31,9 +31,6 @@ jobs:
       - name: 📦 Install dependencies
         run: pnpm install
 
-      - name: 📦 Install browsers
-        run: pnpm playwright install
-
       - name: 🌐 Compare translations
         run: pnpm i18n:check
 
@@ -43,14 +40,4 @@ jobs:
       - name: 🔠 Fix lint errors
         run: pnpm lint:fix
 
-      - name: 🧪 Update unit test snapshots
-        run: pnpm test:unit -u
-
-      - name: 🏃 Update component test snapshots
-        run: pnpm test:nuxt -u
-
-      # TODO: re-enable when we have snapshots in browser tests
-      # - name: 🖥️ Update browser test snapshots
-      #   run: pnpm test:browser --update-snapshots
-
       - uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27

.github/workflows/ci.yml

@@ -32,14 +32,10 @@ jobs:
 
       - uses: pnpm/action-setup@1e1c8eafbd745f64b1ef30a7d7ed7965034c486c
         name: Install pnpm
-        with:
-          cache: true
-
-      - name: 📦 Install dependencies
-        run: pnpm install
+        # pnpm cache skipped deliberately as the project is not actually installed here
 
       - name: 🔠 Lint project
-        run: pnpm lint
+        run: node scripts/lint.ts
 
   test:
     runs-on: ubuntu-latest
@@ -60,7 +56,7 @@ jobs:
         run: pnpm install
 
       - name: 🌐 Install browser
-        run: pnpm playwright install
+        run: pnpm playwright install chromium-headless-shell
 
       - name: 💪 Type check
         run: pnpm test:types
@@ -96,6 +92,9 @@ jobs:
 
   a11y:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        mode: [dark, light]
 
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
@@ -115,10 +114,11 @@ jobs:
       - name: 🏗️ Build project
         run: pnpm build
 
-      - name: ♿ Accessibility audit (Lighthouse - dark & light mode)
+      - name: ♿ Accessibility audit (Lighthouse - ${{ matrix.mode }} mode)
         run: ./scripts/lighthouse-a11y.sh
         env:
           LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
+          LIGHTHOUSE_COLOR_MODE: ${{ matrix.mode }}
 
   knip:
     runs-on: ubuntu-latest

.github/workflows/provenance.yml

@@ -4,21 +4,28 @@ on:
   push:
     branches:
       - main
+    paths:
+      - pnpm-lock.yaml
   pull_request:
     branches:
       - main
+    paths:
+      - pnpm-lock.yaml
   merge_group:
     branches:
       - main
+
 permissions:
   contents: read
+
 jobs:
   check-provenance:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     steps:
       - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
+
       - name: Check provenance downgrades
         uses: danielroe/provenance-action@41bcc969e579d9e29af08ba44fcbfdf95cee6e6c # v0.1.1
         with:

.github/workflows/semantic-pull-requests.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: read # for amannn/action-semantic-pull-request to analyze PRs
       statuses: write # for amannn/action-semantic-pull-request to mark status of analyzed PR
     if: github.repository == 'npmx-dev/npmx.dev'
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     name: semantic-pr
     steps:
       - name: Validate PR title

.lighthouserc.cjs

@@ -29,7 +29,7 @@ module.exports = {
       url: [
         'http://localhost:3000/',
         'http://localhost:3000/search?q=nuxt',
-        'http://localhost:3000/nuxt',
+        'http://localhost:3000/package/nuxt',
       ],
       numberOfRuns: 1,
       chromePath: findChrome(),

CONTRIBUTING.md

@@ -14,6 +14,43 @@ We want to create 'a fast, modern browser for the npm registry.' This means, amo
 - Layout shift, flakiness, slowness is The Worst. We need to continually iterate to create the most performant, best DX possible.
 - We want to provide information in the best way. We don't want noise, cluttered display, or confusing UI. If in doubt: choose simplicity.
 
+## Table of Contents
+
+- [Getting started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+- [Development workflow](#development-workflow)
+  - [Available commands](#available-commands)
+  - [Project structure](#project-structure)
+  - [Local connector CLI](#local-connector-cli)
+- [Code style](#code-style)
+  - [TypeScript](#typescript)
+  - [Server API patterns](#server-api-patterns)
+  - [Import order](#import-order)
+  - [Naming conventions](#naming-conventions)
+  - [Vue components](#vue-components)
+- [RTL Support](#rtl-support)
+- [Localization (i18n)](#localization-i18n)
+  - [Approach](#approach)
+  - [Adding a new locale](#adding-a-new-locale)
+  - [Update translation](#update-translation)
+  - [Adding translations](#adding-translations)
+  - [Translation key conventions](#translation-key-conventions)
+  - [Using i18n-ally (recommended)](#using-i18n-ally-recommended)
+  - [Formatting numbers and dates](#formatting-numbers-and-dates)
+- [Testing](#testing)
+  - [Unit tests](#unit-tests)
+  - [Component accessibility tests](#component-accessibility-tests)
+  - [End to end tests](#end-to-end-tests)
+- [Submitting changes](#submitting-changes)
+  - [Before submitting](#before-submitting)
+  - [Pull request process](#pull-request-process)
+  - [Commit messages and PR titles](#commit-messages-and-pr-titles)
+- [Pre-commit hooks](#pre-commit-hooks)
+- [Using AI](#using-ai)
+- [Questions](#questions)
+- [License](#license)
+
 ## Getting started
 
 ### Prerequisites
@@ -111,7 +148,7 @@ To help with this, the project uses `oxfmt` to handle formatting via a pre-commi
 
 If you want to get ahead of any formatting issues, you can also run `pnpm lint:fix` before committing to fix formatting across the whole project.
 
-### Typescript
+### TypeScript
 
 - We care about good types – never cast things to `any` 💪
 - Validate rather than just assert
@@ -485,6 +522,31 @@ Format: `type(scope): description`
 > [!NOTE]
 > The subject must start with a lowercase letter. Individual commit messages within your PR don't need to follow this format since they'll be squashed.
 
+### PR descriptions
+
+If your pull request directly addresses an open issue, use the following inside your PR description.
+
+```text
+Resolves | Fixes | Closes: #xxx
+```
+
+Replace `#xxx` with either a URL to the issue, or the number of the issue. For example:
+
+```text
+Fixes #123
+```
+
+or
+
+```text
+Closes https://github.com/npmx-dev/npmx.dev/issues/123
+```
+
+This provides the following benefits:
+
+- it links the pull request to the issue (the merge icon will appear in the issue), so everybody can see there is an open PR
+- when the pull request is merged, the linked issue is automatically closed
+
 ## Pre-commit hooks
 
 The project uses `lint-staged` with `simple-git-hooks` to automatically lint files on commit.

README.md

@@ -13,12 +13,16 @@
 
 ## Vision
 
-The aim of [npmx.dev](https://npmx.dev) is to provide a better browser for the npm registry – fast, modern, and accessible. We don't aim to replace the [npmjs.com](https://www.npmjs.com/) registry, just provide a better UI, DX, and admin experience.
+The goal of [npmx.dev](https://npmx.dev) is to build a fast, modern browser for the npm registry.
 
-- **Speed first** – Layout shift, flakiness, slowness is The Worst. Fast searching, filtering, and navigation.
-- **URL compatible** – Replace `npmjs.com` with `xnpmjs.com` or `npmx.dev` in any URL and it just works.
-- **Simplicity** – No noise, cluttered display, or confusing UI. If in doubt: choose simplicity.
-- **Admin UI** – Manage your packages, teams, and organizations from the browser, powered by your local npm CLI.
+We're not replacing the [npmjs.com](https://www.npmjs.com/) registry, but instead providing an elevated developer experience through a fast, modern UI.
+
+What npmx offers:
+
+- **Speed** – Fast searching, filtering, and navigation.
+- **Simplicity** – Get the information you need when you need it in an intuitive UI.
+- **Compatibility** – Replace `npmjs.com` with `xnpmjs.com` or `npmx.dev` in any URL and it just works.
+- **Enhanced admin experience** – Manage your packages, teams, and organizations from the browser, powered by your local npm CLI.
 
 ## Shortcuts
 
@@ -36,7 +40,7 @@ The aim of [npmx.dev](https://npmx.dev) is to provide a better browser for the n
 
 ### Package browsing
 
-- **Dark mode by default** – easier on the eyes
+- **Dark mode and light mode** – plus customize the color palette to your preferences
 - **Fast search** – quick package search with instant results
 - **Package details** – READMEs, versions, dependencies, and metadata
 - **Code viewer** – browse package source code with syntax highlighting and permalink to specific lines
@@ -100,7 +104,7 @@ The aim of [npmx.dev](https://npmx.dev) is to provide a better browser for the n
 
 ### npm compatibility
 
-npmx.dev supports npm permalinks – just replace `npmjs.com` with `npmx.dev` or `xnpmjs.com` and it works:
+npmx.dev supports npm permalinks – just replace `npmjs.com` with `npmx.dev` or `xnpmjs.com` to get the npmx experience:
 
 | npm URL                         | npmx.dev equivalent                                                    |
 | ------------------------------- | ---------------------------------------------------------------------- |
@@ -142,7 +146,7 @@ npmx.dev also supports shorter, cleaner URLs:
 
 ## Contributing
 
-We welcome contributions – please do feel free to poke around and improve things. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to get up and running!
+We welcome contributions – please do feel free to explore the project and improve things. See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to get up and running!
 
 ## Related projects
 
@@ -151,6 +155,7 @@ We welcome contributions – please do feel free to poke around and improve
 - [npm-userscript](https://github.com/bluwy/npm-userscript) – Browser userscript with various improvements and fixes for npmjs.com
 - [npm-alt](https://npm.willow.sh/) – An alternative npm package browser
 - [npkg.lorypelli.dev](https://npkg.lorypelli.dev/) – An alternative frontend to npm made with as little client-side JavaScript as possible
+- [vscode-npmx](https://github.com/npmx-dev/vscode-npmx) – VSCode extension for npmx
 
 If you're building something cool, let us know! 🙏
 

app/app.vue

@@ -21,6 +21,16 @@ const localeMap = locales.value.reduce(
   {} as Record<string, Directions>,
 )
 
+const darkMode = usePreferredDark()
+const colorMode = useColorMode()
+const colorScheme = computed(() => {
+  return {
+    system: darkMode ? 'dark light' : 'light dark',
+    light: 'only light',
+    dark: 'only dark',
+  }[colorMode.preference]
+})
+
 useHead({
   htmlAttrs: {
     'lang': () => locale.value,
@@ -30,6 +40,7 @@ useHead({
   titleTemplate: titleChunk => {
     return titleChunk ? titleChunk : 'npmx - Better npm Package Browser'
   },
+  meta: [{ name: 'color-scheme', content: colorScheme }],
 })
 
 if (import.meta.server) {
@@ -58,7 +69,8 @@ function handleGlobalKeydown(e: KeyboardEvent) {
     router.push('/search')
   }
 
-  if (isKeyWithoutModifiers(e, '?')) {
+  // For "?" we check the key property directly since it's usually combined with shift
+  if (e.key === '?') {
     e.preventDefault()
     showKbdHints.value = true
   }
@@ -68,20 +80,37 @@ function handleGlobalKeyup() {
   showKbdHints.value = false
 }
 
-/* A hack to get light dismiss to work in safari because it does not support closedby="any" yet */
+// Light dismiss fallback for browsers that don't support closedby="any" (Safari + old Chrome/Firefox)
 // https://codepen.io/paramagicdev/pen/gbYompq
 // see: https://github.com/npmx-dev/npmx.dev/pull/522#discussion_r2749978022
 function handleModalLightDismiss(e: MouseEvent) {
   const target = e.target as HTMLElement
   if (target.tagName === 'DIALOG' && target.hasAttribute('open')) {
+    const rect = target.getBoundingClientRect()
+    const isOutside =
+      e.clientX < rect.left ||
+      e.clientX > rect.right ||
+      e.clientY < rect.top ||
+      e.clientY > rect.bottom
+
+    if (!isOutside) return
     ;(target as HTMLDialogElement).close()
   }
 }
 
 if (import.meta.client) {
   useEventListener(document, 'keydown', handleGlobalKeydown)
   useEventListener(document, 'keyup', handleGlobalKeyup)
-  useEventListener(document, 'click', handleModalLightDismiss)
+
+  // Feature check for native light dismiss support via closedby="any"
+  // https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog#closedby
+  const supportsClosedBy =
+    typeof HTMLDialogElement !== 'undefined' &&
+    typeof HTMLDialogElement.prototype === 'object' &&
+    'closedBy' in HTMLDialogElement.prototype
+  if (!supportsClosedBy) {
+    useEventListener(document, 'click', handleModalLightDismiss)
+  }
 }
 </script>