Use npx to manage the download, install, and invocation of Antora
This plugin currently sits in a hybrid mode of operation. First, it downloads and installs the @antora/site-generator-default
package into the current project, which creates a node_modules folder and package.json and package-lock.json files. It then uses npx to run the antora
command from the @antora/cli
package, which is only installed in the npx cache. The plugin needs to pick a lane (or, rather, support two independent lanes).
I propose two separate modes, npx and local, based on what files are present in the current project.
npx mode If there's no package.json file in the project, the plugin will work entirely through npx. That way, the user never sees any residue from running Antora (no node_modules, no package.json, no package-lock.json). It's all tucked neatly away in the npx cache. And there's only one download step.
local mode
If the package.json file is detected, the plugin should assume that it is safe to install the packages in the current project. If package-lock.json is present, the plugin will run npm ci
. Otherwise, it will run npm i
(without creating package-lock.json). It will then use npx to run the antora
command, but that bin script will be located within the project (not in the npx cache).
In npx mode, the plugin will install the package named "antora". In the future, we can allow additional packages (aka dependencies) to be specified in the antora extension block.
In local mode, the plugin will not try to install an Antora package. Rather, it will assume that the package is already declared in package.json. It will assume that one of the declared packages provides the antora
command (though perhaps it could work even if it doesn't?)
One of the nice things about npx is that, even though the packages are installed out of view, it doesn't change the current working directory. I thought about emulating the behavior of npx...but ultimately got suck at how to do it without changing the current working directory. Therefore, it makes sense to just rely on the behavior of npx.
Keep in mind that npx creates a unique cache folder per combination of packages passed to the npx command. Furthermore, we can configure the npx cache to use the npmWorkDir as defined by the Node plugin.