docs(node): add section on pinning npm version by jdx · Pull Request #8925 · jdx/mise

jdx · 2026-04-05T17:52:01Z

Summary

Adds a "Pinning npm version" section to the Node.js docs showing how to pin a specific npm version alongside Node
Shows both the mise.toml approach and the mise use --pin CLI approach
Verified in Docker that both tool orderings work correctly and the pinned npm overrides Node's bundled version

Test plan

Verified npm:npm pinning works in Docker container (Ubuntu 24.04)
Verified mise use --pin node@lts resolves to exact version
Verified mise use --pin npm@latest resolves to exact version
Verified ordering doesn't matter in mise.toml (node before npm and npm before node both work)

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only change describing how to pin npm versions; no runtime or behavioral code changes.

Overview
Adds a new “Pinning npm version” section to the Node docs explaining how to manage npm as a separate tool alongside node in mise.

Includes examples for setting versions in mise.toml and using mise use --pin to resolve aliases like lts/latest to exact versions, clarifying that pinned npm overrides the bundled Node npm.

^{Reviewed by Cursor Bugbot for commit 3a04c77. Bugbot is set up for automated code reviews on this repo. Configure here.}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gemini-code-assist

Code Review

This pull request adds a new section to the Node.js documentation explaining how to pin npm versions alongside Node.js in mise.toml. A review comment suggests combining the separate pinning commands for Node and npm into a single command to improve efficiency.

gemini-code-assist · 2026-04-05T17:54:16Z

+mise use --pin node@lts
+mise use --pin npm@latest


You can pin both Node and npm versions in a single command for better efficiency and to update the mise.toml file in one go.

Suggested change

mise use --pin node@lts

mise use --pin npm@latest

mise use --pin node@lts npm@latest

greptile-apps · 2026-04-05T17:54:25Z

Greptile Summary

This documentation-only PR adds a "Pinning npm version" section to docs/lang/node.md, explaining how to lock a specific npm version alongside Node.js to ensure team consistency and avoid package-lock.json conflicts.

Key changes:

New section showing mise.toml configuration with node = "24" and npm = "11" as major-version pins
Documents mise use --pin node@lts npm@latest for resolving aliases to exact pinned versions (e.g. node = "24.14.1", npm = "11.12.1")
Clarifies that the pinned npm takes precedence over Node's bundled npm (consistent with overrides = ["node"] in registry/npm.toml)
Version examples are internally consistent throughout the new section

Confidence Score: 5/5

Safe to merge immediately — pure documentation with no runtime or behavioral changes.

No issues found. The npm tool name is confirmed valid via registry/npm.toml (backends = ['npm:npm'], overrides = ['node']). Version examples are internally consistent (node = '24' aligns with the resolved node = '24.14.1'). The previously flagged version inconsistency (node='22') has already been addressed in the current diff.

No files require special attention.

Important Files Changed

Filename	Overview
docs/lang/node.md	Adds a 'Pinning npm version' section documenting how to lock npm alongside Node via mise.toml or `mise use --pin`; technically accurate, consistent version examples, and well-placed in the document structure.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Need consistent npm version across team] --> B{Choose approach}
    B --> C["Manual: edit mise.toml directly"]
    B --> D["CLI: mise use --pin node@lts npm@latest"]
    C --> E["[tools]\nnode = \"24\"\nnpm = \"11\""]
    D --> F["Aliases resolved to exact versions\nnode = \"24.14.1\"\nnpm = \"11.12.1\""]
    E --> G[mise installs both tools]
    F --> G
    G --> H["npm --version returns pinned version\n(overrides Node's bundled npm)"]
    H --> I[Consistent npm across all team machines]

_{Reviews (3): Last reviewed commit: "docs: update npm pinning example to node..." | Re-trigger Greptile}

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Node 24 is current LTS. The unpinned example showed node 22 while the pinned output showed 24.14.1, which could confuse readers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-05T18:26:23Z

Hyperfine Performance

`mise x -- echo`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 x -- echo`	18.4 ± 0.5	17.3	23.4	1.00
`mise x -- echo`	19.4 ± 0.6	18.2	24.8	1.05 ± 0.05

`mise env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 env`	18.2 ± 0.7	17.2	24.0	1.00
`mise env`	18.8 ± 0.4	17.7	20.1	1.04 ± 0.04

`mise hook-env`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 hook-env`	18.6 ± 1.2	17.7	36.6	1.00
`mise hook-env`	19.4 ± 2.2	18.3	66.4	1.04 ± 0.13

`mise ls`

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
`mise-2026.4.4 ls`	17.2 ± 1.0	16.0	33.5	1.00
`mise ls`	17.9 ± 0.7	17.0	27.4	1.04 ± 0.07

`xtasks/test/perf`

Command	mise-2026.4.4	mise	Variance
install (cached)	117ms	117ms	+0%
ls (cached)	67ms	68ms	-1%
bin-paths (cached)	69ms	70ms	-1%
task-ls (cached)	716ms	706ms	+1%

@SamSoldatenko

### 🚀 Features - **(config)** report env files in config ls and doctor output by @SamSoldatenko in [#8853](#8853) - add support for token sources in GitLab and Forgejo by @roele in [#8868](#8868) ### 🐛 Bug Fixes - **(aqua)** prevent double .exe extension when Windows override URL already ends in .exe by @yusei-wy in [#8863](#8863) - **(bash)** avoid duplicate trust warning after cd by @timothysparg in [#8920](#8920) - **(env)** prevent config root injection into PATH via _.source by @jdx in [#8936](#8936) - **(install)** suppress spurious dependency warning when tool is configured by @jdx in [#8923](#8923) ### 📚 Documentation - **(node)** add section on pinning npm version by @jdx in [#8925](#8925) - add Windows default paths and mise.toml examples alongside CLI commands by @jdx in [#8926](#8926) - clarify common sources of confusion from GitHub discussions by @jdx in [#8927](#8927) - clarify Python venv mechanisms, JAVA_HOME behavior, and activation performance by @jdx in [#8928](#8928) - add FAQ and troubleshooting entries based on common Discord questions by @jdx in [#8930](#8930) ### New Contributors - @SamSoldatenko made their first contribution in [#8853](#8853) - @yusei-wy made their first contribution in [#8863](#8863)

docs(node): add section on pinning npm version

6eb1f01

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

gemini-code-assist Bot reviewed Apr 5, 2026

View reviewed changes

greptile-apps Bot reviewed Apr 5, 2026

View reviewed changes

Comment thread docs/lang/node.md

jdx enabled auto-merge (squash) April 5, 2026 17:55

jdx and others added 2 commits April 5, 2026 17:57

docs(node): use single mise use command for node+npm pinning

9ccbf97

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: update npm pinning example to node 24 for consistency

3a04c77

Node 24 is current LTS. The unpinned example showed node 22 while the pinned output showed 24.14.1, which could confuse readers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

jdx merged commit 331609f into main Apr 5, 2026
37 checks passed

jdx deleted the docs/node-npm-pinning branch April 5, 2026 18:20

mise-en-dev mentioned this pull request Apr 5, 2026

chore: release 2026.4.5 #8921

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(node): add section on pinning npm version#8925

docs(node): add section on pinning npm version#8925
jdx merged 3 commits intomainfrom
docs/node-npm-pinning

jdx commented Apr 5, 2026 •

edited by cursor Bot

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Apr 5, 2026

Uh oh!

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

	mise use --pin node@lts
	mise use --pin npm@latest
	mise use --pin node@lts npm@latest

Uh oh!

Conversation

jdx commented Apr 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Apr 5, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 5, 2026

Hyperfine Performance

mise x -- echo

mise env

mise hook-env

mise ls

xtasks/test/perf

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jdx commented Apr 5, 2026 •

edited by cursor Bot

Loading

greptile-apps Bot commented Apr 5, 2026 •

edited

Loading

`mise x -- echo`

`mise env`

`mise hook-env`

`mise ls`

`xtasks/test/perf`