Node.js package management

Package installation

Posit Connect installs the npm package dependencies of Node.js content when that content is deployed. Connect uses npm to install the packages into a per-bundle environment, then uses that environment at runtime.

Node.js version matching selects the Node.js installation that Connect uses for a piece of content. Connect uses the same installation for both package installation and content execution, so the npm binary must be present in the same directory as the configured NodeJs.Executable. Standard Node.js distributions include npm by default.

Required bundle files

Bundles for Node.js content must include both package.json and package-lock.json. Connect rejects bundles that are missing either file.

Connect reads package.json to select a Node.js installation through the engines.node field and to identify the bundle’s npm dependencies. Connect requires package-lock.json so that the server installs the same package versions as the publisher’s environment. The npm ci install step also requires the lock file to be consistent with package.json. Commit package-lock.json to your source repository alongside package.json.

Important

Connect does not generate package-lock.json for you. If your project does not have a lock file, run npm install once locally to create one before deploying.

Connect does not support other Node.js package managers, such as pnpm and yarn. Connect uses npm and looks for package-lock.json.

Reproducible installs

Connect runs the following command during the environment build:

Terminal

npm ci --omit=dev

npm ci installs the exact versions recorded in package-lock.json without modifying the lock file. The --omit=dev flag tells npm to skip packages listed under devDependencies in package.json. Move any package that the running application requires from devDependencies into dependencies before deploying.

Build duration

NodeJs.MaxEnvironmentBuildDuration controls the maximum duration of a Node.js environment build and defaults to 20 minutes. If your application has a long npm install time, raise this value.

Environment management

By default, Connect manages the npm packages that a Node.js application requires at runtime. Connect manages the environment during content deployment by running npm ci --omit=dev against the bundle’s package.json and package-lock.json. The resulting node_modules tree is then available at runtime when the content executes.

The Node.js environment management behavior can be controlled by either an administrator or the content owner. When environment management is disabled, the administrator is responsible for ensuring that the packages required by the bundle are available in the runtime environment.

Specifically, npm packages must be available through Node.js’s standard module resolution starting from the bundle directory. The most reliable approach is to install dependencies before deployment and include the resulting node_modules/ directory in the bundle. The selected Node.js installation can be found in the General tab under the Information section in the content settings panel.

There are two ways to configure the Node.js environment management strategy. From lowest to highest precedence:

1. Server administrators can configure a global environment management strategy at the server level with the NodeJs.EnvironmentManagement setting. The default value is true.

2. Publishers can configure a bundle-level environment management strategy. If set, this option is always used, and the global server-level default is ignored. To set a bundle-level environment management strategy, publishers can set the environment.environment_management.nodejs field in the bundle manifest.json. The Applications.ManifestEnvironmentManagementSelection setting (enabled by default) gates this per-bundle override.

Configuring the npm registry

By default, npm installs packages from the public npm registry at https://registry.npmjs.org. To install packages from a private registry or an internal mirror, configure npm using .npmrc files. npm reads .npmrc files in the order documented in the npm .npmrc reference.

Server-level .npmrc

To apply registry settings to every Node.js environment build on the server, place an .npmrc file at one of these locations:

• /etc/npmrc. Applies to all users on the system.
• ~/.npmrc for the user account named in Applications.RunAs. Applies to environment builds run by Connect. For example, if Applications.RunAs is rstudio-connect, the file is at /home/rstudio-connect/.npmrc.

For example, to point npm at an internal mirror:

/etc/npmrc

registry=https://npm.example.com/

Bundle-level .npmrc

Publishers can include an .npmrc file in their bundle to apply project-specific registry settings. Settings in the bundle .npmrc override the server-level settings.

Authenticating to a registry

If your registry requires authentication (for example, a private registry with access controls), provide credentials in an .npmrc file using a registry-scoped authentication token:

/etc/npmrc

registry=https://npm.example.com/
//npm.example.com/:_authToken=<your-api-token>

Warning

Credentials in a server-level .npmrc are accessible to all deployed content running on the server. Use registry tokens with the narrowest scope possible (for example, read-only access).

Proxy configuration

If your Connect server reaches the npm registry through an HTTP proxy, configure the proxy using the Packages.HTTPProxy and Packages.HTTPSProxy settings. Connect sets the http_proxy and https_proxy environment variables for the npm process during the environment build.

/etc/rstudio-connect/rstudio-connect.gcfg

[Packages]
HTTPProxy = http://proxy.example.com:3128
HTTPSProxy = http://proxy.example.com:3128

Private packages from Git repositories

npm supports installing packages directly from Git repositories by including a Git URL in package.json:

package.json

{
  "dependencies": {
    "mypackage": "git+https://github.com/mycompany/mypackage.git#v1.2.3"
  }
}

When package-lock.json resolves a dependency to a Git URL, the Connect environment build invokes git through npm to fetch the package. In the default Connect configuration, the build process runs with the home directory of the Applications.RunAs user as HOME. For private repositories, place a .netrc file in that home directory, or configure an SSH key for that user that has access to the required repositories.

Note

If Applications.HomeMounting is enabled, the build process sees /home as HOME instead of the Applications.RunAs user’s home directory, and the approaches above do not work. Embed an HTTPS access token in the Git URL in package.json if your Git host supports it.

Note

The Connect-managed GitCredential entries used by R and Python environment restoration do not apply to npm Git installs. Configure Git credentials for the Applications.RunAs user directly.

Native modules and system dependencies

Some npm packages depend on a working C or C++ toolchain and on system libraries. See Native modules and system dependencies in the Node.js admin section for guidance.