> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# studion/core

Core commands for Node.js projects, install dependencies with caching by default and run scripts, using npm or pnpm package manager. Tailored for use within Studion pipelines.


## Commands

### ensure_pkg_manager

Ensure required package manager is in place, optionally specifing the exact version. Requires execution environment with Node.js >= 18.20 pre-installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `ref` | string | ${DEFAULT_PKG_MANAGER} | Choose Node.js package manager to use. Supports npm and pnpm.
The package manager must follow the format <name>[@<version|tag>].
Omitting the version implies
(for npm) use the version that comes with the target Node.js environment,
(for pnpm) use the existing version if found, otherwise use the latest version.
 |

### install_dependencies

Install dependencies with caching, optionally choose a package manager. Requires execution environment with Node.js >= 18.20 pre-installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_version` | string | v1 | Change the default cache version if the cache needs to be cleared for some reason. |
| `install_command` | string |  | Custom command to install dependencies. Useful when default commands, "npm ci" or "pnpm i --frozen-lockfile", are unsuitable.
 |
| `pkg_json_dir` | string | . | Path to the directory containing package.json file. Not needed when package.json is in the root.
 |
| `pkg_manager` | string | ${DEFAULT_PKG_MANAGER} | Choose Node.js package manager to use. Supports npm and pnpm.
The package manager must follow the format <name>[@<version|tag>].
Omitting the version implies that the npm version is determined by the target Node.js environment,
while pnpm will default to the latest version.
 |

### run_script

Simple command that enables running scripts defined within package.json. Requires execution environment with Node.js >= 18.20 pre-installed.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cache_version` | string | v1 | Change the default cache version if the cache needs to be cleared for some reason. |
| `install_command` | string |  | Custom command to install dependencies. Useful when default commands, "npm ci" or "pnpm i --frozen-lockfile", are unsuitable.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as "20m", "1.25h", "5s".
 |
| `pkg_json_dir` | string | . | Path to the directory containing package.json file. Not needed when package.json is in the root.
 |
| `pkg_manager` | string | ${DEFAULT_PKG_MANAGER} | Choose Node.js package manager to use. Supports npm and pnpm.
The package manager must follow the format <name>[@<version|tag>].
Omitting the version implies that the npm version is determined by the target Node.js environment,
while pnpm will default to the latest version.
 |
| `script` | string |  | Name of the script to execute. Passed as is to the run command of choosen pacakge manager, meaning it can contain arguments as well.
 |
| `skip_install_dependencies` | boolean | false | The flag indicating whether to skip installing dependencies.
Useful in a case of multiple `run_script` commands inside a single job.
 |

## Executors

### node

Docker executor using CI-optimized Node.js image built to run on CircleCI.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Choose the executor resource class |
| `tag` | string | lts | Choose a specific cimg/node image tag: https://hub.docker.com/r/cimg/node/tags
 |

### node_secrets

Docker executor integrating Infisical Open Source Secret Management for secure secret retrieval within CircleCI Node.js pipelines.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Choose the executor resource class |
| `tag` | string | lts | Choose a specific studiondev/node-secrets image tag: https://hub.docker.com/r/studiondev/node-secrets/tags
 |

### ubuntu

Docker executor using CI-optimized Ubuntu image built to run on CircleCI.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Choose the executor resource class |
| `tag` | string | current | Choose a specific cimg/base image tag: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### npm_run

Run any script defined inside a "package.json" using the targeted package manager.
Before running the specified script, the command will fetch the code and install dependencies.


```yaml
version: '2.1'
orbs:
  core: studion/core@x.y.z
jobs:
  test:
    executor: core/node
    steps:
      - checkout
      - core/run_script:
          pkg_manager: npm
          script: test
workflows:
  test_app:
    jobs:
      - test
```

### pnpm_ensure

Ensure the desired package manager, including the version, is installed on the system.
If desired, the package manager can be set through the DEFAULT_PKG_MANAGER environment variable.
The npm is used to update itself and to install pnpm when required.


```yaml
version: '2.1'
orbs:
  core: studion/core@x.y.z
jobs:
  audit:
    executor: core/node
    steps:
      - core/ensure_pkg_manager:
          ref: pnpm@9.0.1
      - run: pnpm audit --prod
workflows:
  audit_deps:
    jobs:
      - audit
```

### pnpm_install

By default, the "install_dependencies" command respects automated environments
and installs dependencies consistently and predictably.
There is an option to override the install command, package manager, and root directory.


```yaml
version: '2.1'
orbs:
  core: studion/core@x.y.z
jobs:
  build:
    executor:
      name: core/node
      resource_class: xlarge
      tag: 20.11.0
    steps:
      - checkout
      - core/install_dependencies:
          cache_version: v3
          install_command: pnpm i
          pkg_json_dir: ~/workspace/project
          pkg_manager: pnpm
      - run: cd ~/workspace/project && pnpm run build
workflows:
  build_app:
    jobs:
      - build
```