Node.js
This is an Early Access feature. See the Early Access documentation for more information.
The Early Access release does not support off-host execution. Node.js content runs only in local-execution mode. On a Posit Connect server configured for off-host execution (Kubernetes.Enabled = true), Node.js deploys fail with “no compatible environment found.”
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 and open 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. Install Node.js using the distribution of your choice; pre-built binaries are available from https://nodejs.org/en/download.
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/nodejs/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
Node.js support is disabled by default. While Node.js is in Early Access, administrators must opt in by setting EarlyAccess.NodeJs to true in addition to setting NodeJs.Enabled to true. Configure NodeJs.Executable with the path to each Node.js binary you want to make available.
/etc/rstudio-connect/rstudio-connect.gcfg
[EarlyAccess]
NodeJs = true
[NodeJs]
Enabled = true
Executable = /opt/nodejs/22.18.0/bin/node
Executable = /opt/nodejs/24.3.0/bin/nodeIf NodeJs.Enabled is true while EarlyAccess.NodeJs is false, Connect fails to start with the error NodeJs.Enabled is in Early Access. Enable EarlyAccess.NodeJs to continue.
You can support multiple Node.js versions by providing an Executable for each. Each NodeJs.Executable value can be a symbolic link to a Node.js installation.
Connect does not auto-discover Node.js installations from PATH or any well-known directory. Without at least one NodeJs.Executable entry, Connect cannot run Node.js content.
Upgrading Node.js
We recommend supporting multiple versions of Node.js instead of upgrading and maintaining a single version. Supporting multiple versions of Node.js is the best way to ensure content published with specific package dependencies continues to run.
After installing another Node.js version:
Add an additional
NodeJs.Executableproperty to the configuration file that points to the newly installed Node.js binary.
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
You can view the available Node.js versions on your Connect server by navigating to System > Info > System Info in the Connect UI.
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"
}
}Connect treats engines.node as a target version, not a SemVer range. Connect extracts the first MAJOR.MINOR.PATCH value from engines.node (for example, 22.18.0 from >=22.18.0) and matches that target against the available installations. Range syntax beyond a leading version, such as >=22.18.0 <23.0.0 or 22.x, is not interpreted as a range. Only the leading three-part version is used.
Specify the version you want to target as MAJOR.MINOR.PATCH, optionally with a SemVer prefix such as >= or ^.
If engines.node is not set in package.json, Connect uses the latest available Node.js installation.
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.