From 4b33d362ab21c2dadc97819d77de3b15b2a7a876 Mon Sep 17 00:00:00 2001 From: mahabaleshwars <147705296+mahabaleshwars@users.noreply.github.com> Date: Tue, 2 Dec 2025 12:32:34 +0530 Subject: [PATCH] update documentation for lockfile --- README.md | 2 +- docs/advanced-usage.md | 22 +++++++++++++++++++++- 2 files changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e49c1172..49aa9562 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ Since it will not be cached always, there is possibility of hitting rate limit w ### Checking in lockfiles -It's **always** recommended to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide. +It's **strongly recommended** to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide. ## Caching global packages data diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 851e261b..b436c096 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -1,12 +1,14 @@ ## Working with lockfiles -All supported package managers recommend that you **always** commit the lockfile, although implementations vary doing so generally provides the following benefits: +Most supported package managers recommend that you **always** commit the lockfile, although implementations vary doing so generally provides the following benefits: - Enables faster installation for CI and production environments, due to being able to skip package resolution. - Describes a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies. - Provides a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself. - Facilitates greater visibility of tree changes through readable source control diffs. +**However, for libraries, not using a lockfile may be preferable to ensure testing with the latest transitive dependencies. See the [Node.js Package Maintenance Working Group documentation on dependency management guidelines](https://github.com/nodejs/package-maintenance/blob/main/docs/dependency-management-guidelines.md#using-lockfiles) for a discussion of tradeoffs.** + In order to get the most out of using your lockfile on continuous integration follow the conventions outlined below for your respective package manager. ### NPM @@ -35,6 +37,24 @@ Ensure that `pnpm-lock.yaml` is always committed, when on CI pass `--frozen-lock - [Working with Git - Lockfiles](https://pnpm.io/git#lockfiles) - [Documentation of `--frozen-lockfile` option](https://pnpm.io/cli/install#--frozen-lockfile) +### Running without a lockfile + +If you choose not to use a lockfile, you must ensure that **caching is disabled**. The `cache` feature relies on the lockfile to generate a unique key for the cache entry. + +To run without a lockfile: +1. Do not set the `cache` input. +2. If your `package.json` specifies a `packageManager` (which enables automatic caching in v5+), explicitly disable it: + +```yaml +steps: +- uses: actions/checkout@v5 +- uses: actions/setup-node@v6 + with: + node-version: '24' + package-manager-cache: false # Explicitly disable caching if you don't have a lockfile +- run: npm install +- run: npm test + ## Check latest version The `check-latest` flag defaults to `false`. When set to `false`, the action will first check the local cache for a semver match. If unable to find a specific version in the cache, the action will attempt to download a version of Node.js. It will pull LTS versions from [node-versions releases](https://github.com/actions/node-versions/releases) and on miss or failure will fall back to the previous behavior of downloading directly from [node dist](https://nodejs.org/dist/). Use the default or set `check-latest` to `false` if you prefer stability and if you want to ensure a specific version of Node.js is always used.