action.yml

name: Setup pnpm with runtime
description: Install pnpm and a JavaScript runtime (Node.js, Bun, or Deno) in one step
branding:
  icon: package
  color: orange
inputs:
  version:
    description: |
      Version of pnpm to install: an exact version (`12.0.0`), a
      semver range (`^12.0.0`), or an npm dist-tag (`next-12`). Must resolve
      to pnpm v11 or newer — the action downloads pnpm's native per-platform
      executable directly, without needing Node.js or npm.

      When omitted, the version is read from `devEngines.packageManager` or
      `packageManager` in the project's package.json.
    required: false
  registry:
    description: |
      npm registry to resolve and download pnpm from, e.g. a mirror on a
      network that cannot reach registry.npmjs.org. Defaults to
      `https://registry.npmjs.org/`; registry environment variables such as
      `pnpm_config_registry` do not change it.

      The mirror has to proxy the npm registry rather than re-publish pnpm:
      the download is verified against npm's own signature, which it must
      pass through unchanged. This only affects how pnpm itself is fetched —
      configure pnpm's own `registry` setting, e.g. `pnpm_config_registry`,
      for `pnpm install`.
    required: false
  dest:
    description: Where to store pnpm files
    required: false
    default: ~/setup-pnpm
  runtime:
    description: |
      Runtime to install, in `<name>` or `<name>@<version>` form (matching
      pnpm's `packageManager` field syntax). Supported names: `node`, `bun`,
      `deno`. Examples: `node@22`, `node@lts`, `node@^24.4.0`, `bun@latest`,
      `deno@2`.

      When the version is omitted, the action falls back to the version
      declared in `devEngines.runtime` for the same name, or to `lts` (for
      `node`) / `latest` for others. For Node.js, an explicit version file
      overrides the manifest; automatically detected files are used after
      the manifest and before the `lts` fallback.

      If this input is omitted entirely, the action installs every runtime in
      `devEngines.runtime` from the project's package.json. In case of duplicates,
      the last declared version wins. Node.js is also installed when a
      version file supplies its version, unless an explicit Bun or Deno
      runtime was selected.

      Whenever a runtime is installed, the action exports
      `PNPM_CONFIG_GLOBAL_SHIMS` with that runtime's context-aware shim
      disabled, so later steps run exactly this version instead of one a
      project pins. Set the variable in the workflow to override.
    required: false
  node-version-file:
    description: |
      File containing the Node.js version to install, relative to
      `working-directory`. When omitted, automatically checks `.node-version`,
      `.nvmrc`, then `.tool-versions` if no Node.js version is declared in
      `devEngines.runtime`. Set to `false` to disable version-file detection.
      An explicit file path takes precedence over `devEngines.runtime`.

      When `runtime` is omitted, this installs Node.js alongside any non-Node
      runtimes declared in `devEngines.runtime`. A version included directly
      in `runtime` takes precedence, and an explicit Bun or Deno runtime
      ignores version files. `.tool-versions` uses the first version in its
      `node` or `nodejs` entry; automatic detection ignores it without that entry.
    required: false
  cache:
    description: |
      Whether to cache the pnpm store directory, keyed on the lockfile's
      content hash, and restore it before installing the runtimes. The
      results of pnpm's lockfile verification are cached either way — see
      the README.
    required: false
    default: 'false'
  save-cache:
    description: |
      Whether to save the pnpm store at the end of the job when `cache` is
      `true`. Set to `false` to only restore it, for example in jobs that
      should not write to the cache. The lockfile verification cache is
      saved either way.
    required: false
    default: 'true'
  cache-dependency-path:
    description: |
      File path to the pnpm lockfile, whose contents hash is used as a cache
      key. Relative to the repository root (GITHUB_WORKSPACE). Defaults to
      the shared workspace lockfile for workspace members, or `pnpm-lock.yaml`
      inside `working-directory` for standalone and per-project installs.
    required: false
  working-directory:
    description: |
      Directory the project lives in, relative to the repository root
      (GITHUB_WORKSPACE). The action runs `pnpm install` there and resolves
      `node-version-file` relative to it. For workspace members, package-manager
      selection and shared-lockfile caching follow the workspace root.
      Defaults to the repository root.

      pnpm finds the workspace root itself by walking up, so a project
      inside a pnpm workspace does not need this — point it at a project
      whose root is not the repository root.
    required: false
    default: '.'
  package-json-file:
    description: |
      Deprecated. Use `working-directory` instead: the manifest is read
      from that directory, which is also where `pnpm install` runs. Still
      honoured when set on its own — the directory containing the file
      becomes the working directory.
    required: false
    deprecationMessage: 'The package-json-file input is deprecated; use working-directory instead.'
  require-lockfile:
    description: |
      Whether the install has to be fully described by `pnpm-lock.yaml`.

      When `true`, the action fails if no lockfile is found — in
      `working-directory` or, as pnpm itself searches, above it — without
      running pnpm at all, and otherwise runs the install with
      `--frozen-lockfile`.

      This is narrower than it sounds. pnpm already refuses to update an
      *existing* lockfile when it detects CI, and GitHub Actions always sets
      `CI`, so an out-of-date lockfile fails a plain install anyway. What that
      default does not do is require a lockfile to exist: with none at all,
      `pnpm install` resolves from the registry, writes one and exits 0. Set
      this when that should fail the job instead.
    required: false
    default: 'false'
  install:
    description: |
      Whether to run `pnpm install` after pnpm and the runtime are set up.

      When set to `true` (the default), the action runs `pnpm install` in the
      workspace when a package.json is present. When runtimes are installed,
      `--no-runtime` is appended automatically because the action has already
      processed `devEngines.runtime`.

      Set to `false` to skip the install step — useful for jobs that only
      need pnpm itself (e.g. `pnpm audit`, lockfile-only regeneration).
    required: false
    default: 'true'
  token:
    description: >
      No longer used. pnpm is fetched from the npm registry and verified
      against npm's signature, so no GitHub API request is made. Kept so
      workflows that pass it keep working.
    required: false
    deprecationMessage: 'The token input is no longer used; pnpm is fetched from the npm registry.'

outputs:
  dest:
    description: Expanded path of inputs#dest
  bin-dest:
    description: Location of `pnpm` and `pnpx` command
  runtime-name:
    description: Name of the first installed runtime (`node`, `bun`, or `deno`), or empty if none was installed
  runtime-version:
    description: Resolved version of the first installed runtime, or empty if none was installed
  runtimes:
    description: JSON array of installed runtimes, each containing `name` and `version`
  cache-hit:
    description: Whether the restored cache matched the current lockfile exactly, rather than falling back to a store cached for a different lockfile
runs:
  using: node24
  main: dist/index.js
  post: dist/index.js