From 750b84cad6c535ea344abd1eb9e1c30b75bf1fbc Mon Sep 17 00:00:00 2001 From: leekeh <71131586+leekeh@users.noreply.github.com> Date: Tue, 4 Aug 2026 17:46:25 +0200 Subject: [PATCH 1/4] fix: use oxc as default formatter in vscode to prevent formatting diffs --- .vscode/settings.json | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/.vscode/settings.json b/.vscode/settings.json index ead94c6acf..d03f13095a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -7,5 +7,20 @@ "explorer.fileNesting.enabled": true, "explorer.fileNesting.patterns": { "*.vue": "${capture}.stories.ts" + }, + "[json]": { + "editor.defaultFormatter": "oxc.oxc-vscode" + }, + "[jsonc]": { + "editor.defaultFormatter": "oxc.oxc-vscode" + }, + "[typescript]": { + "editor.defaultFormatter": "oxc.oxc-vscode" + }, + "[vue]": { + "editor.defaultFormatter": "oxc.oxc-vscode" + }, + "[yaml]": { + "editor.defaultFormatter": "oxc.oxc-vscode" } } From 09726122ccc41ca4dabf2e74126207ad1c60ab4c Mon Sep 17 00:00:00 2001 From: leekeh <71131586+leekeh@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:30:14 +0200 Subject: [PATCH 2/4] feat: enhance and algin CONTRIBUTING.md --- CONTRIBUTING.md | 51 ++++++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e153c57fde..c03602b672 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,7 +63,6 @@ This focus helps guide our project decisions as a community and what we choose t - [Test fixtures (mocking external APIs)](#test-fixtures-mocking-external-apis) - [Storybook](#storybook) - [Component categories](#component-categories) - - [Coverage guidelines](#coverage-guidelines) - [Project conventions](#project-conventions) - [Configuration](#configuration) - [Global app settings](#global-app-settings) @@ -73,7 +72,6 @@ This focus helps guide our project decisions as a community and what we choose t - [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) @@ -82,8 +80,10 @@ This focus helps guide our project decisions as a community and what we choose t ### Prerequisites -- [Node.js](https://nodejs.org/) (LTS version recommended) -- [pnpm](https://pnpm.io/) v10.28.1 or later +- [Node.js](https://nodejs.org/) +- [pnpm](https://pnpm.io/) + +Please use the version pinned in the `engines.node` and `packageManager` field of [package.json](./package.json). ### Setup @@ -100,7 +100,13 @@ This focus helps guide our project decisions as a community and what we choose t pnpm dev ``` -4. (optional) if you want to test the admin UI/flow, you can run the local connector: +4. start the connector with mock data: + + ```bash + pnpm mock-connector + ``` + + or with real data (requires npm login): ```bash pnpm npmx-connector @@ -169,7 +175,7 @@ rm -rf .nuxt/cache/nitro/handlers/ rm -rf .nuxt/cache/nitro/handlers/npmx-picks/ ``` -Alternatively, you can bypass the cache entirely in development by adding `shouldBypassCache: () => import.meta.dev` to your `defineCachedEventHandler` options: +Alternatively, you can bypass the cache for a specific API entirely in development by adding `shouldBypassCache: () => import.meta.dev` to your `defineCachedEventHandler` options: ```ts export default defineCachedEventHandler( @@ -227,7 +233,7 @@ The connector will check your npm authentication, generate a connection token, a ### Mock connector (for local development) -If you're working on admin features (org management, package access controls, operations queue) and don't want to use your real npm account, you can run the mock connector instead: +If you don't want to use your real npm account, you can run the mock connector instead: ```bash pnpm mock-connector @@ -257,11 +263,7 @@ pnpm mock-connector --empty # start with no prepopulated data ## Code style -When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes. - -To help with this, the project uses `oxfmt` to handle formatting via a pre-commit hook. The hook will automatically reformat files when needed. If something can’t be fixed automatically, it will let you know what needs to be updated before you can commit. - -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. +When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes. To prevent this, you can configure your IDE to use `oxc` as the formatter, which is aligned with the linter used inside the workflows for this project. Alternatively, you can manually run `pnpm lint:fix` before committing to fix formatting across the whole project. ### npmx name @@ -796,7 +798,7 @@ docker run --rm \ -e NODE_OPTIONS="--max-old-space-size=4096" \ -v $(pwd):/work \ -w /work \ - mcr.microsoft.com/playwright:v1.58.2-noble \ + mcr.microsoft.com/playwright:v1.62.1-noble \ sh -c "npm install -g pnpm && pnpm install && pnpm vp run build:test && pnpm vp run test:browser:prebuilt --update-snapshots" ``` @@ -827,6 +829,16 @@ Fixtures are stored in `test/fixtures/` with this structure: ``` test/fixtures/ +├── algolia/ +│ └── search/ # Algolia search results +├── esm-sh/ +│ ├── doc-nodes/ # Parsed documentation nodes (exports, types, functions) +│ ├── headers/ # esm.sh response headers (used to resolve type declarations) +│ └── types/ # TypeScript type declaration files +├── github/ # GitHub API responses (contributor stats) +├── jsdelivr/ # jsDelivr Data API responses (package file lists) +├── jsdelivr-cdn/ # jsDelivr CDN responses (raw package file content) +├── microlink/ # Microlink API responses (homepage link previews) ├── npm-registry/ │ ├── packuments/ # Package metadata (vue.json, @nuxt/kit.json) │ ├── search/ # Search results (vue.json, nuxt.json) @@ -883,7 +895,6 @@ cli/src/ ├── mock-app.ts # H3 mock app + MockConnectorServer class └── mock-server.ts # CLI entry point (pnpm mock-connector) -test/test-utils/ # Re-exports from cli/src/ for test convenience test/e2e/helpers/ # E2E-specific wrappers (fixtures, global setup) ``` @@ -972,14 +983,10 @@ Single-use components that encapsulate one feature. - **Testing focus:** Layout, responsive behavior, integration testing - **Coverage:** Critical user flows and breakpoints -### Coverage guidelines - -#### Which Components Need Stories? - -TBD - ### Project conventions +Stories should follow the [Component Story Format (CSF)](https://storybook.js.org/docs/api/csf). + #### Place `.stories.ts` files next to the component ```sh @@ -1224,10 +1231,6 @@ 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. - ## Using AI You're welcome to use AI tools to help you contribute. But there are two important ground rules: From 8e84cc2fb785efe165639345072771a4192f8145 Mon Sep 17 00:00:00 2001 From: leekeh <71131586+leekeh@users.noreply.github.com> Date: Tue, 4 Aug 2026 19:48:54 +0200 Subject: [PATCH 3/4] fix: restore + update precommit info --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c03602b672..3d1ca34a0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,6 +72,7 @@ This focus helps guide our project decisions as a community and what we choose t - [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) @@ -265,6 +266,8 @@ pnpm mock-connector --empty # start with no prepopulated data When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes. To prevent this, you can configure your IDE to use `oxc` as the formatter, which is aligned with the linter used inside the workflows for this project. Alternatively, you can manually run `pnpm lint:fix` before committing to fix formatting across the whole project. +Before you commit, staged files will automatically be linted and formatted using a [pre-commit hook](#pre-commit-hooks). + ### npmx name When displaying the project name anywhere in the UI, use `npmx` in all lowercase letters. @@ -1231,6 +1234,19 @@ 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 + +Before commiting, the following things will run against staged files: + +- **`*.{js,ts,mjs,cjs,vue}`** — `vp lint --fix` (auto-fix lint errors) +- **`*.vue`** — UnoCSS class checker +- **`*.{js,ts,mjs,cjs,vue,json,yml,md,html,css}`** — `vp fmt` (auto-format) +- **`i18n/locales/*`** — regenerate Lunaria tracking data and `i18n/schema.json` + +If something can't be fixed automatically, the commit will be blocked. Run `pnpm lint:fix` beforehand to resolve any issues proactively. + +The configuration for the pre-commit hook is defined in the [`staged` block of vite.config.ts](vite.config.ts#L168-L174) and is automatically installed by running `vp config`, which will run any time you run `pnpm install`. + ## Using AI You're welcome to use AI tools to help you contribute. But there are two important ground rules: From a938289e1d8bda88834a0f557feda6545a4f3024 Mon Sep 17 00:00:00 2001 From: leekeh <71131586+leekeh@users.noreply.github.com> Date: Tue, 4 Aug 2026 20:29:36 +0200 Subject: [PATCH 4/4] fix: typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d1ca34a0f..85a0fe81e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1236,7 +1236,7 @@ This provides the following benefits: ## Pre-commit hooks -Before commiting, the following things will run against staged files: +Before committing, the following things will run against staged files: - **`*.{js,ts,mjs,cjs,vue}`** — `vp lint --fix` (auto-fix lint errors) - **`*.vue`** — UnoCSS class checker