Skip to content

docs(cli): align direct npm dependencies during manual installation - #3157

Merged
fengmk2 merged 3 commits into
voidzero-dev:mainfrom
SaKaNa-Y:docs/npm-manual-overrides
Oct 26, 2026
Merged

fengmk2 merged 3 commits into
voidzero-dev:mainfrom
SaKaNa-Y:docs/npm-manual-overrides

Conversation

@SaKaNa-Y

@SaKaNa-Y SaKaNa-Y commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

When manually migrating an npm project with an existing vite dependency, the guide tells readers to add an alias override but leaves the original dependency unchanged. npm rejects the conflicting specifications with EOVERRIDE, so the next install fails.

Add an npm-specific note and example that show how to align the existing dependency with its override:

 "devDependencies": {
-  "vite": "^8.0.0",
+  "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
   "vite-plus": "1.3.0"
 },
 "overrides": {
   "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
   "vitest": "5.0.5"
 }

The note also explains the same requirement for an existing direct vitest dependency and tells readers to reinstall after editing the manifest.

Evidence

Verified with npm 11.19.0 using npm install --ignore-scripts --no-audit --no-fund in isolated projects.

  • Before: A direct vite: "^8.0.0" dependency conflicts with the alias override. Installation fails with EOVERRIDE.
    After: The example extracted from the updated documentation installs successfully. The installed vite alias resolves to @voidzero-dev/vite-plus-core.
  • Before: A direct vitest: "^5.0.5" dependency conflicts with the exact 5.0.5 override.
    After: Using 5.0.5 for both installs successfully.
  • A project without a direct vite dependency also installs successfully.
  • The focused formatting check and git diff --check pass. Independent diff review found no issues.

Merge Danger

Door: two-way

Blast Radius: documentation

Only the project-local CLI guide changes. No CLI behavior changes.

@SaKaNa-Y
SaKaNa-Y marked this pull request as ready for review October 25, 2026 04:40
@SaKaNa-Y

Copy link
Copy Markdown
Contributor Author

This PR adds the missing npm manual migration step to prevent installation failures when direct dependency specifications conflict with overrides.

Automatic migration does not have this issue.

@fengmk2 fengmk2 self-assigned this Oct 26, 2026
@fengmk2
fengmk2 merged commit 60ba76b into voidzero-dev:main Oct 26, 2026
39 checks passed
@SaKaNa-Y
SaKaNa-Y deleted the docs/npm-manual-overrides branch October 26, 2026 08:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants