Node.js
Posit Connect supports deploying Node.js content.
A compatible version of Node.js is identified when content is deployed. That Node.js installation is used any time Node.js is needed for that content. Package installation and starting Node.js content both use the version of Node.js discovered at deploy-time.
Connect allows different content to rely on different versions of Node.js. For example, Alice’s application might require Node.js 22.18.0 while Bob’s application needs Node.js 24.3.0. Those two deployments using different Node.js versions can coexist in Connect without conflict.
This section discusses how to install Node.js, how Connect can be configured to support one or more versions of Node.js, how Node.js version compatibility is determined, and other configuration settings relevant to Node.js support in Connect.
Available Node.js installations are analyzed at startup. Connect logs the provided Node.js versions and whether it can use each installation.
Changing any of the configuration items discussed in this section requires a restart of Connect.
License requirements
Running Node.js content requires the Advanced tier of Connect. Connect verifies the entitlement both at deploy time and when a Node.js worker starts.
To check your license tier and entitlements, click System in the Connect top menu bar, then click the Info tab. The System Info section lists your License Tier and Entitlements. For more details, see the Licensing section or contact your Posit account representative.
Installing Node.js
You are responsible for installing Node.js on your Connect server. Connect does not bundle a Node.js runtime, and does not provide an installer.
The minimum supported Node.js version is 22.18.0. Connect does not enforce a maximum version, and admins can install any 22.18.0-or-later release. Connect tests against the Node.js Long-Term Support (LTS) lines and recommends them for production use. The supported lines are Active LTS and Maintenance LTS.
If a configured NodeJs.Executable points to a binary that Connect cannot use, Connect cannot initialize Node.js support and fails to start. The startup logs identify the offending installation and version. Remove the entry or replace it with a 22.18.0-or-later binary, then start Connect.
At runtime, the worker selects a Node.js installation based on the bundle’s package.json. If no installed Node.js version satisfies the declared engines.node value, the worker logs Unable to locate a Node.js installation matching constraint ... and the content does not start.
We recommend installing Node.js into a version-specific directory, such as /opt/node/22.18.0, so that multiple versions can be installed side-by-side. Avoid installing Node.js with a system package manager like apt, yum, or zypper. System packages typically install a single version under a shared path, which makes it harder to support multiple Node.js versions and to upgrade without disrupting deployed content.
Once you have Node.js installed on the server, Node.js version matching explains how Connect chooses the Node.js version that an asset uses.
Enabling Node.js support
The package-installed starter configuration enables Node.js support and scans versioned installations beneath /opt/node. Connect starts successfully when Node.js is enabled without a discovered installation. Running Node.js content still requires the Advanced tier or an Evaluation license.
/etc/rstudio-connect/rstudio-connect.gcfg
[NodeJs]
Enabled = true
ExecutableVersionScanning = /opt/nodeUse NodeJs.Enabled to disable Node.js support. Use the NodeJs.Executable setting to explicitly enumerate installations outside a versioned directory layout. You can support multiple versions by providing an Executable for each. Each value can be a symbolic link to a Node.js installation.
Scanning
Posit Connect can scan administrator-configured directories for Node.js installations and optionally use PATH.
- Version scanning: Looking for Node.js in locations known to contain multiple version installations. Disabled by default.
- Path scanning: Looking for Node.js using the
PATHenvironment variable. Disabled by default, and only occurs if a Node.js installation is not otherwise discovered or configured.
The following configuration snippet shows both scanning settings.
/etc/rstudio-connect/rstudio-connect.gcfg
[NodeJs]
ExecutableVersionScanning = /opt/node
ExecutablePathScanning = falseVersion scanning
Version scanning examines direct child directories beneath each configured root. Each Node.js installation must contain an executable at bin/node. Connect does not match other executable names that contain node, and it does not search nested directories. For example, these installations are detected when /opt/node is configured:
/opt/node/22.18.0/bin/node
/opt/node/v22.22.1/bin/node
/opt/node/24.14.0/bin/nodeSymbolic links from a version directory to another installation location are permitted.
Version scanning is configured with NodeJs.ExecutableVersionScanning, which accepts one or more absolute directory paths. It is disabled when no paths are configured.
/etc/rstudio-connect/rstudio-connect.gcfg
[NodeJs]
; Scan direct child directories beneath /opt/node:
ExecutableVersionScanning = /opt/node
; Add an additional scan directory:
ExecutableVersionScanning = /some/other/path/node
ExecutableVersionScanning = /opt/node-extra
; An empty value is ignored:
ExecutableVersionScanning =Use NodeJs.Executable instead if your organization uses a different directory layout.
Path scanning
Posit Connect can use the PATH environment variable to discover Node.js if an installation is not otherwise found. Path scanning is disabled by default and can be enabled with NodeJs.ExecutablePathScanning.
/etc/rstudio-connect/rstudio-connect.gcfg
[NodeJs]
ExecutablePathScanning = trueUsing PATH typically provides only one Node.js installation. Versioned installations provide a more stable environment for content with different Node.js requirements.
Excluding versions
To exclude installations found by scanning, disable Node.js scanning and explicitly list the versions Connect should use with NodeJs.Executable.
Upgrading Node.js
We recommend supporting multiple versions of Node.js rather than upgrading and maintaining one Node.js executable. Keeping older versions available is the best way to ensure content published with specific package dependencies continues to run.
After installing another Node.js version:
Install the new version beneath a configured version-scanning directory, or add a
NodeJs.Executableproperty that points to the new binary.
Posit Connect can use the Node.js version you installed.
You can also update an existing installation in place, for example from 22.18.0 to a later 22.x release. Point the NodeJs.Executable entry at the new binary and restart Posit Connect. Replacing a version this way removes it as a fallback for content that depends on it.
Following an upgrade, content dependent on Node.js is rebuilt on demand. The next time someone requests the content, Connect reinstalls the npm dependencies for the matched Node.js version before serving traffic.
Rebuilding and restoring packages can take a significant amount of time and can delay the availability of content. NodeJs.MaxEnvironmentBuildDuration controls the maximum environment build time, defaulting to 20 minutes. Raise this value if your applications have unusually long npm install times.
Not all npm packages reinstall cleanly on newer Node.js major versions. Native modules in particular might need updating to support a new Node.js major version.
Node.js version matching
View the Node.js runtime state in the Connect UI at System > Info > System Info. The page reports whether the runtime is disabled, not permitted by the license, enabled with no versions found, or enabled with discovered versions. For each local installation, the page also reports the executable path.
Restart Connect after you install a runtime version so Connect can discover the installation.
Connect selects a Node.js installation for published content based on the version constraint declared in the bundle’s package.json file. Connect reads the engines.node field and matches the value against the Node.js installations available on the server. For the field format, see the npm engines reference.
Example package.json segment:
package.json
{
"engines": {
"node": ">=22.18.0"
}
}When more than one installed Node.js version satisfies the range, Connect selects the highest matching version. If engines.node cannot be parsed as a SemVer range, the deploy fails with Could not parse Node.js version constraint.
If engines.node is not set in package.json, Connect uses the latest available Node.js installation.
Restricting versions for new content
Supporting several Node.js versions keeps existing content running, but you might still want new content to target a more recent version. The NodeJs.PublishableVersions setting takes a version specifier that content must satisfy when it is first published:
/etc/rstudio-connect/rstudio-connect.gcfg
[NodeJs]
PublishableVersions = ">=24.0.0"The specifier uses npm semver range syntax, the same syntax content uses for engines.node, so ranges such as ^24.0.0 or >=22.18.0 <25.0.0 are also accepted. This differs from the PEP 440 syntax used by R.PublishableVersions and Python.PublishableVersions. The setting is empty by default, which places no restriction on the Node.js version used by new content.
The specifier takes part in Node.js version matching, so content is first published on a version you allow whenever one exists. Connect selects the newest installation satisfying both engines.node and this setting. For example, with Node.js 20, 22, and 24 installed and PublishableVersions = "<24", content whose engines.node is >=20 is first published on Node.js 22 rather than 24. Content that does not set engines.node is first published on the newest installation you allow rather than the newest installed.
Publishing fails when no installed version satisfies both engines.node and this setting. Connect reports that no compatible environment was found and lists the Node.js versions available.
The restriction applies only the first time a piece of content is published. After content has been published once, later deployments to that same content item are not restricted – including deployments that select an older, excluded version – and rebuilding an existing bundle is never restricted. Excluded Node.js installations therefore remain available to content that is already deployed, so existing applications continue to run, and you can tighten the policy without disrupting content and the maintenance of that content which predates the restriction.
Native modules and system dependencies
Many npm packages include native code that node-gyp or a similar build tool compiles during installation. These packages depend on a working C or C++ toolchain and on system libraries that match the package’s needs. For example, sharp requires libvips, and canvas requires Cairo, Pango, and related libraries.
Connect does not install these system dependencies for you. The Connect server administrator must ensure that any system libraries and build tools required by deployed content are present on the Connect server.
When npm install fails for a piece of content, the Connect deploy logs identify the failing package. Use that information to install the missing system dependencies, then redeploy the content.
TypeScript
Connect supports TypeScript content. Supported Node.js versions, 22.18.0 and later, execute TypeScript natively without a build step. Connect does not include a TypeScript compiler and does not transpile TypeScript at deploy time.