Provides a modern test CLI for ESM support to @oclif v2 against Node 12.20.0+ and 14.13+.
There are three test suites for ESM support for Oclif v2:
- test-cli-modern (this one) / everything works as expected
- test-cli-cjs-interop / workaround for CJS named exports (widest Node support)
- test-cli-experimental-modules / usage of --experimental-modules + workaround for CJS named exports (not recommended / demo only)
This test CLI and Github Action CI / CD test suite covers the versions of Node that fully support modern ESM without
requiring --experimental-modules or the CJS named export workaround starting at 12.20.0 and all of 14.13.0.
A discussion issue about ESM support has concluded with a merge of ESM
support on the @oclif/core repo. Please see this comment
on updated details on how to publish an ESM Oclif v2 CLI before the full launch of Oclif v2.
Click here to view the latest Action CI / CD run
(requires a valid Github login). The test suite is run in a matrix supporting macos-latest, ubuntu-latest, windows-latest
on Node versions 12.20.0, 12.x, 14.13.0, 14.x, 16.0.0 and 16.x.
All the test suites use @oclif/core 0.5.10+.
For testing the CLI is invoked locally along with a programmatic tests.
It should be noted that everything is ESM from the test CLI to the test suite itself. This test suite verifies which versions of Node support what can be considered as modern ESM not requiring any workarounds. This "modern" version is suggested to be the main project format that is generated by the Oclif CLI / project creator for ESM based CLIs.
Take note that in package.json "type": "module" is set. As things go this requires the bin bootstrap file
./bin/run to be renamed to ./bin/run.js to support ESM. Unlike test-cli-experimental-modules the bootstrap
file is straightforward and invokes Node as per normal.
The test source contains a programmatic test
and spawn tests. To
accomplish the spawn test cross-platform with Windows cross-spawn
is utilized and the local bootstrap code, ./bin/run.js is invoked. The programmatic tests demonstrate fancy-test
and use of chai-as-promised invoking the main package export
via ./src/index.js. These tests cover execution for the CLI across MacOS, Ubuntu, and Windows with the Node versions
one can create a modern ESM Oclif CLI that requires no workarounds.
nyc does not support code coverage for ESM based tests in Mocha presently. The
solution is to use c8 which does work with ESM tests and is a drop in replacement
for nyc. This repo uses Codecov to publish a coverage report
in the GH Action. When running tests locally a ./coverage directory is created that contains the coverage report. As
can be seen in the report full coverage of both the CLI command / init files and bin bootstrap occurs.
While there is newly added ESM support to @oclif/core v0.5.10+ the rest of the Oclif v2 infrastructure and plugins are
not updated to use @oclif/core yet. This is somewhat problematic in using @oclif/dev-cli v1.26.0 and in particular the
oclif-dev manifest CLI command in the prepack or prepublishOnly NPM scripts. There is a workaround though to
publish ESM Oclif v2 CLIs using the oclif-dev manifest command. It requires installing all dependencies from Oclif v2
then manually updating @oclif/config which is the v1 version depended on by @oclif/dev-cli. ESM support has been
back-ported with a hard fork of @oclif/config v1 in this repository.
The contents of the lib directory from the above repository needs to be copied into node_modules/@oclif/config/lib as
it adds ESM config loading support to @oclif/config v1
Note: This workaround only works with oclif-dev manifest command and not the README command.
A comment tracking the current best practice or procedure to publish an ESM Oclif v2 CLI is posted here. When Oclif v2 fully launches no workarounds will be necessary.