bazel-contrib / bazel-contrib/rules_nodejs

Support generic Node.js version configuration files in `node.toolchain

Open
#3,922 0 comments 1 reaction 0 assignees View on GitHub
Dominant language
Starlark
Stars
762
Forks
531
Avg merge
10h 31m
Merged PRs (30d)
3

Description

Currently, `rules_nodejs` provides the following configuration for specifying the Node.js version:

```python
node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")

node.toolchain(
node_version_from_nvmrc = "//:.nvmrc",
)

use_repo(node, "nodejs_toolchains")
```

The `node_version_from_nvmrc` option is specifically tied to the `.nvmrc` file format.

However, many modern Node.js projects use other Node.js version management tools and configuration files, such as:

- `.node-version` (nodenv, mise, etc.)
- `.tool-versions` (asdf)
- `package.json` `engines.node`
- other project-specific version management configurations

This makes `node_version_from_nvmrc` difficult to adopt in existing repositories where the Node.js version is already defined by another tool.

## Motivation

In many monorepos, the Node.js version is already managed by tools such as:

- mise
- asdf
- nodenv
- volta
- nvm

For example:

```
.node-version
```

or:

```
.tool-versions
```

When Bazel is introduced into an existing repository, requiring an additional `.nvmrc` file only for `rules_nodejs` creates duplicated configuration and may cause version drift.

A more generic Node.js version source mechanism would make `rules_nodejs` easier to integrate with existing workflows.

## Proposed Change

Consider introducing a generic Node.js version configuration API instead of coupling the API to `.nvmrc`.

For example:

```python
node.toolchain(
node_version_from_file = "//:.node-version",
)
```

or:

```python
node.toolchain(
node_version_file = "//:.node-version",
)
```

The implementation could support different file formats or provide an extensible mechanism for custom version sources.

Example:

```python
node.toolchain(
node_version_file = "//:.tool-versions",
node_version_file_format = "asdf",
)
```

Alternatively, the API could support a generic resolver abstraction:

```python
node.toolchain(
node_version_source = "//tools/node_version:resolver",
)
```

where different version sources can be implemented independently.

## Expected Behavior

The Node.js toolchain should be able to resolve the Node.js version from common project configuration files.

Examples:

### `.nvmrc`

```
20.15.0
```

### `.node-version`

```
20.15.0
```

### `.tool-versions`

```
nodejs 20.15.0
```

The resolved version should then be used to configure the Bazel Node.js toolchain.

## Questions

1. Is `node_version_from_nvmrc` intentionally limited to `.nvmrc` support?

2. Would the maintainers consider introducing a generic Node.js version source API?

3. Would a contribution adding support for `.node-version` or other Node.js version files be considered?

## Additional Context

The current API:

```python
node_version_from_nvmrc
```

appears to couple the toolchain configuration with a specific Node.js version manager (`nvm`).

The underlying requirement is not specifically about `nvm`, but about resolving the Node.js version from a repository-level configuration source.

A more generic abstraction could improve compatibility with different Node.js ecosystem workflows and make `rules_nodejs` easier to adopt in modern monorepo environments.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.