---
title: "Use npm with a lock file for JavaScript · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/languages-and-runtimes/npm
updated: 2026-10-21
licence: "All rights reserved"
---

# Use npm with a lock file for JavaScript packages

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- Level: Recommended
- Chapter: [Languages and runtimes](https://agentwranglers.se/playbook/stack/languages-and-runtimes)
- Rule: Use the npm that ships with your Node.js line, commit `package-lock.json`, and install with `npm ci` in builds.
- Cost: Open source. The npm command is Artistic-2.0 licensed and the public registry is free. Private packages on the registry are paid.
- How: npm passes all five tests. It ships inside every Node.js release, and the registry lists npm releases from 2013. Version 12.2.0 shipped in September 2026. In the Stack Overflow Developer Survey 2026, 54.6% of developers used it. It uses the Artistic-2.0 licence, which the OSI approves. The lock file makes every install pick the same versions, as [Lock and audit dependencies](https://agentwranglers.se/playbook/adversarial-testing/supply-chain-and-setup/audit-dependencies) requires. Choose something else when a repository holds many packages or installs are slow, where pnpm is the pick. pnpm 1.0 shipped in June 2017, 12.14.0 shipped in October 2026, and it is MIT licensed.
- Check: `package-lock.json` is committed. Every build runs `npm ci`, never `npm install`. The repository has no `yarn.lock` or second lock file.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```sh
npm install --save-exact zod
npm ci
npm audit --audit-level=high
```

### YAML example

```yaml
steps:
  - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
    with:
      node-version: 24
      cache: npm
  - run: npm ci
  - run: npm test
```

## Sources

- [npm ci](https://docs.npmjs.com/cli/commands/npm-ci)
- [pnpm](https://pnpm.io/)

## Related rules

- [Lock and audit dependencies](https://agentwranglers.se/playbook/adversarial-testing/supply-chain-and-setup/audit-dependencies) in Security testing

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/stack/languages-and-runtimes/npm">Agent Wranglers software choices playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Use Python for data work and as a second server language](https://agentwranglers.se/playbook/stack/languages-and-runtimes/python)
- Next: [Use pip and a virtual environment for Python packages](https://agentwranglers.se/playbook/stack/languages-and-runtimes/pip-and-venv)
- [Languages and runtimes](https://agentwranglers.se/playbook/stack/languages-and-runtimes)