[ANN] First release of opam-check-npm-deps plugin 1.0.0

Community
, , , ,
1

I am happy to announce on behalf of the Ahrefs and Melange teams the first release 1.0.0 of the opam-check-npm-deps opam plugin.

This plugin aims to solve a simple limitation: how to allow libraries written for either Melange or Js_of_ocaml to define dependencies to JavaScript packages. It addresses the problem by enabling library authors to leverage the depexts field in opam files to define dependencies on npm packages.

For library authors: defining constraints

Constraints are defined by adding an entry to depexts with the npm package
name as the “system package” and an equality formula that matches the
npm-version variable to a version range. This range can be defined using the
same format as the dependencies field in a package.json file [1].

For example, the reason-react bindings can define their dependency on the
react and react-dom npm packages like this:

depexts: [
  ["react"] {npm-version = "^16.0.0 || ^17.0.0"}
  ["react-dom"] {npm-version = "^16.0.0 || ^17.0.0"}
]

Or, to simplify:

depexts: [
  ["react" "react-dom"] {npm-version = "^16.0.0 || ^17.0.0"}
]

For library users: checking npm dependencies status

Users can check the state of the npm dependencies by running the plugin:

$ opam-check-npm-deps
Ok: opam package "test.dev" requires npm package: "react" with constraint "^16.0.0 || ^17.0.0", version installed: "17.0.2"
Ok: opam package "test.dev" requires npm package: "react-dom" with constraint "^16.0.0 || ^17.0.0", version installed: "17.0.2"

The plugin will provide information when errors occur:

$ opam-check-npm-deps
Error: opam package "test.dev" requires npm package "react" with constraint "^16.0.0 || ^17.0.0", but the version installed found in file "node_modules/react/package.json" is "18.2.0"
Error: opam package "test.dev" requires npm package "react-dom" with constraint "^16.0.0 || ^17.0.0", but the version installed found in file "node_modules/react-dom/package.json" is "18.2.0"

When running the plugin, it checks the current opam switch to read all depexts fields that use the npm-version variable, and then reads the node_modules folder to determine if the constraints are satisfied.

Compatibility

The plugin is currently compatible with version 2.1 of opam.

Upcoming plans and ecosystem collaboration

Our next steps will involve testing this initial version with Melange libraries and projects, and gathering feedback from the community about use cases and functionality. We will also keep an eye on the release of opam 2.2 for an upgrade. If you have suggestions about how to improve the plugin or find any bugs, please open an issue in the project repository.

It is exciting to release a tool that can be useful for both Js_of_ocaml and Melange developers. I hope that both ecosystems discover more areas for potential convergence in the future.

Happy coding!

  1. Special thanks to the esy authors and contributors, as the plugin reuses many of esy’s libraries to analyze constraints in a format compatible with package.json files. ↩︎

8 Likes
2

Nice,

I wonder if jsoo users faced similar issues as packages they depend on might break, and if running this as part of their CI/development would be good here.