nodejs

Synopsis

  • Installs a pinned Node.js release from a prebuilt tarball served by the PUL mirror, optionally enables Corepack-managed Yarn, runs npm dependency installs, and executes Webpack builds with configurable per-environment scripts.

  • The distro-packaged nodejs is removed by default to avoid PATH shadowing (see nodejs_remove_apt_node).

Parameters

Parameter

Comments

deploy

string

Deploy directory path set by the deploy role. Used as the ultimate fallback for nodejs_npm_install_path.

deploy_user

string

Deployment user name set by the deploy_user role. Used as the first fallback for nodejs_build_user.

desired_nodejs_version

string

Legacy variable name that nodejs_version falls back to. Set this during migration; prefer nodejs_version for new work.

django_user

string

Legacy application user name. Used as the second fallback for nodejs_build_user when deploy_user is not set.

nodejs_build_user

string

Unix user that owns the npm/webpack build steps. Falls back to deploy_user, then django_user, then root.

Default: ""

nodejs_download_delay

integer

Delay in seconds between download retries.

Default: 10

nodejs_download_retries

integer

Number of retries for the Node.js tarball download.

Default: 6

nodejs_download_timeout

integer

Timeout in seconds for the Node.js tarball download.

Default: 600

nodejs_install_method

string

Installation method. Currently only prebuilt (download a tarball from the PUL mirror) is supported.

Default: "prebuilt"

nodejs_npm_enabled

boolean

Run an npm dependency install step (used by the build_npm workflow).

Choices:

  • false ← (default)

  • true

nodejs_npm_install_mode

string

npm install strategy. production runs npm install --production, ci runs npm ci, dev runs npm install including devDependencies.

Default: "production"

nodejs_npm_install_path

string

Target directory for npm install. Falls back to npm_install_path then deploy.

Default: ""

nodejs_prefix_root

string

Installation prefix. Node.js binaries are placed under {{ nodejs_prefix_root }}/bin.

Default: "/usr/local"

nodejs_release_base_url

string

Base URL for the Node.js tarball mirror. Override only when using a local or alternative mirror.

Default: "https://pulmirror.princeton.edu/mirror/nodejs"

nodejs_remove_apt_node

boolean

When true, remove the distro-packaged nodejs apt package before installing the prebuilt release to prevent PATH conflicts.

Choices:

  • false

  • true ← (default)

nodejs_version

string

Node.js release to install. Accepts both "22.4.0" and "v22.4.0" formats. Falls back to desired_nodejs_version when set (legacy group_vars migration path).

Default: "22.4.0"

nodejs_webpack_build_commands

dictionary

Mapping of runtime_env name to the npm script invoked by Webpack. Extend per-app in group_vars. Defaults map staging to build:qa and production/preproduction to build:prod.

Default: {"preproduction": "build:prod", "production": "build:prod", "staging": "build:qa"}

nodejs_webpack_debug

boolean

Enable verbose Webpack build output for troubleshooting.

Choices:

  • false ← (default)

  • true

nodejs_webpack_enabled

boolean

Run a Webpack build step after npm install.

Choices:

  • false ← (default)

  • true

nodejs_webpack_stats_check

boolean

When true, verify that webpack-stats.json exists after the build. Set to false if the app does not use webpack-bundle-tracker.

Choices:

  • false

  • true ← (default)

nodejs_webpack_stats_default

string

Computed default path for webpack-stats.json, typically {{ nodejs_npm_install_path }}/sitemedia/webpack-stats.json.

Default: ""

nodejs_webpack_stats_file

string

Explicit path to webpack-stats.json. When empty, the role uses nodejs_webpack_stats_default.

Default: ""

nodejs_yarn_enabled

boolean

Enable Corepack-managed Yarn (Berry). Classic Yarn via apt is not supported by this role.

Choices:

  • false ← (default)

  • true

nodejs_yarn_version

string

Yarn release version to activate via Corepack.

Default: "4.15.0"

npm_install_path

string

Alternate name for nodejs_npm_install_path used by legacy group_vars. nodejs_npm_install_path falls back to this when not set directly.

webpack_build_prod

string

Legacy override for the production and preproduction entries in nodejs_webpack_build_commands. Prefer setting nodejs_webpack_build_commands directly.

webpack_build_qa

string

Legacy override for the staging entry in nodejs_webpack_build_commands. Prefer setting nodejs_webpack_build_commands directly.

Authors

  • Center for Digital Humanities @ Princeton