Skip to content

Node.js

lsp_utils.NodeManager

Resolves a Node.js runtime and installs servers that run on Node.js.

on_pre_start_async classmethod 

on_pre_start_async(context: OnPreStartContext, plugin_storage_path: Path, server_directory_resource_path: ResourcePath, server_binary_path: Path, *, node_version_requirement: str, skip_npm_install: bool = False, on_server_installed: ServerInstalledCallback | None = None) -> Path | None

Initialize NodeManager for an LspPlugin.

Automatically adds support for a root server_path package setting that defaults to "auto", meaning that the package-managed server instance will be used. It can be overridden to use a custom server binary.

When the lsp_utils-managed Node.js runtime is used, its binary directory is prepended to the server's PATH so that any processes spawned by the server that call node use that same runtime.

Parameters:

Name Type Description Default
context OnPreStartContext

The plugin context.

 required
plugin_storage_path Path

The path to the plugin's storage (cls.plugin_storage_path).

 required
server_directory_resource_path ResourcePath

The ResourcePath to the directory that contains the server's package.json file. Must have a Packages/<package_name>/ prefix followed by the path to the directory containing package.json within the package.

 required
server_binary_path Path

The path of the file used to start the server, relative to the server's directory that contains package.json. For example Path('node_modules', 'server', 'start.js').

 required
node_version_requirement str

NPM semantic version (typically a range) specifying which Node.js version is required by the server. Examples:

  • 16.1.1 - only allows a single version
  • 16.x - allows any build for major version 16
  • >=16 - allows version 16 and above
  • 16 - 18 - allows any version between 16 and 18 inclusive (spaces around the dash are required)

See also: https://semver.npmjs.com/

 required
on_server_installed ServerInstalledCallback | None

Callback called when the server gets installed or updated. Gets passed the Path to the server directory (containing 'package.json').

 None

Returns:

Type Description
Path | None

Path to the server directory (containing 'package.json') if the server is managed. The directory name includes a hash of the installation inputs so it changes when the server or Node.js is updated.

resolve classmethod 

resolve(package_name: str, required_node_version: str) -> NodeRunner

Return a Node.js runtime that satisfies the required version.

The runtimes listed in the nodejs_runtime lsp_utils setting are tried in order. The system runtime uses Node.js found on the PATH and the local runtime uses Node.js installed by lsp_utils in the package storage, downloading it if needed.

Parameters:

Name Type Description Default
package_name str

The name of the package that requires Node.js. Used in messages and logs.

 required
required_node_version str

NPM semantic version (typically a range) specifying which Node.js version is required. See node_version_requirement of on_pre_start_async.

 required

Returns:

Type Description
NodeRunner

The resolved runtime.

lsp_utils.NodeRunner 

NodeRunner()

A Node.js runtime, as returned by NodeManager.resolve.

install_node 

install_node() -> None

Install this Node.js runtime.

Raises:

Type Description
Exception

If this runtime doesn't support installation, as is the case for one found on the PATH.

node_binary_path 

node_binary_path() -> Path

Return the path to the node binary.

additional_paths 

additional_paths() -> list[str]

Directories that should be prepended to the PATH so that node resolves to this runtime.

node_env 

node_env() -> dict[str, str]

Return environment variables that need to be set when running node.

apply_env 

apply_env(env: dict[str, str]) -> None

Update env in place with the variables needed to run this runtime's node.

Merges in node_env() and puts additional_paths() first on the PATH so that node resolves to this runtime, also in processes spawned by the started process.

check_binary_present 

check_binary_present() -> None

Check that both the node and the npm binaries were found.

Raises:

Type Description
NodeNotInitializedError

If either of the binaries is missing.

check_satisfies_version 

check_satisfies_version(required_node_version: NpmSpec) -> None

Check that the version of this runtime satisfies the requirement.

Parameters:

Name Type Description Default
required_node_version NpmSpec

The version specification to satisfy.

 required

Raises:

Type Description
Exception

If the version doesn't satisfy the requirement.

resolve_version 

resolve_version() -> Version

Return the version of Node.js.

run_node 

run_node(args: list[str | PathLike[str]], stdin: int = PIPE, stdout: int = PIPE, stderr: int = PIPE, env: dict[str, Any] | None = None) -> Popen[bytes]

Start node with the given arguments and return the process.

run_install 

run_install(cwd: str | PathLike[str]) -> None

Install the production dependencies of the npm project in cwd with npm ci.

npm_command 

npm_command() -> list[Path]

Return the command prefix for running npm.

Raises:

Type Description
NodeNotInitializedError

If the npm binary was not found.

install_project_dependencies 

install_project_dependencies(source_path: ResourcePath, target_path: Path, *, skip_npm_install: bool = False, on_server_installed: ServerInstalledCallback | None = None) -> None

Install the server into target_path, replacing an installation with outdated dependencies.

Deprecated: use install_versioned_project_dependencies instead. Replacing the files of a server that might still be running fails on Windows if the files are locked.

install_versioned_project_dependencies 

install_versioned_project_dependencies(source_path: ResourcePath, parent_path: Path, *, skip_npm_install: bool = False, on_server_installed: ServerInstalledCallback | None = None) -> Path

Install the server into a <parent_path>/<source directory name>-<hash> directory.

The hash depends on package.json, package-lock.json and the Node.js version so an update installs into a new directory instead of replacing files of a server that might still be running.

Returns:

Type Description
Path

The path to the server directory.