Package Management

Packages, often referred to as dependenices, are software libraries for Node.js that contain one or more Antora or Asciidoctor extensions. These extensions, once installed by the plugin, registered in a playbook, and enabled in the playbook or CLI, integrate with Antora to apply additional or alternative functionality to Antora or Asciidoctor.

There are several ways you can specify the Antora and Asciidoctor extension packages, as well as the version of each package, the plugin should install. The packages can be managed using:

  • build.gradle,

  • package.json (with or without package-lock.json), or

  • PACKAGES comment line in a playbook retrieved by the playbook provider

When package.json is present, the plugin won’t install any extension packages declared in build.gradle or the PACKAGES comment in the playbook.

Register and enable extensions

Even if an extension is installed, Antora won’t use it unless it’s registered and enabled. To learn about registering and enabling extensions with Antora, see:

packages property in build.gradle

Extension packages can be defined using the packages property on the antora extension block in your build.gradle file. This is the preferred method for managing packages in your playbook project.

build.gradle
antora {
    packages = [
        '@antora/collector-extension': 'latest'
    ]
}

The value of the packages property contains additional Node.js packages you want to install. The key of each entry is the name of the package and the value is an exact version (e.g., 1.0.0), version tag (e.g., latest), or version range specifier (e.g., ~2.1). This syntax is the same you use when defining dependencies in package.json.

The antora package and any packages listed in this property are automatically downloaded and installed into a cache directory. The node_modules folder, package.json file, and package-lock.json file will not be created in the project. If you want to hide away the details of using npm, this is the right option for you.

package.json

The second way to define packages is with a package.json file.

package.json
"dependencies": {
  "antora": "latest",
  "@antora/collector-extension": "latest"
}

When the package.json file is present, and it contains a dependencies or devDependencies block with at least one entry, the packages property on the antora extensions block is not used. Instead, the plugin will automatically run npm i --no-package-lock to install the dependencies. This command will populate the node_modules folder in the project without creating a package-lock.json file.

The settings in .npmrc are honored when the plugin runs npm i. You can use this file to tune how npm operates. For example, you can set fund=false to suppress the funding notice.

If the @antora/cli package is not installed after npm i is run, the plugin will automatically download and install it into a private area when invoking the antora command via npx.

With package-lock.json

The third way to define additional Node.js packages is with both the package.json file and package-lock.json file. This is a variation of the previous approach, except the plugin will run npm ci instead of npm i. The benefit of using a package-lock.json file is that it locks the versions of the packages that npm installs.

The settings in .npmrc are honored when the plugin runs npm i. You can use this file to tune how npm operates. For example, you can set fund=false to suppress the funding notice.

Again, if the @antora/cli package is not installed after npm ci is run, the plugin will automatically download and install it into a private area when invoking the antora command via npx.

PACKAGES comment in a playbook template

Finally, you can configure packages using the PACKAGES comment line in a playbook template that’s retrieved by the playbook provider feature of the plugin. This is the preferred method for managing packages in your content branches.

The PACKAGES comment is only recognized when the playbook is retrieved through this mechanism. If you’re not using the playbook provider, this comment line is not recognized.

To learn how to manage packages using the PACKAGES comment line and playbook provider, see Playbook Provider.

Precedence

Declaration Location Precedence

package.json

If package.json is present, and it has a dependencies or devDependencies block with at least one entry, it overrides all package and version declarations made using the packages property and PACKAGES comment line.

packages in build.gradle

If the same package is declared in both build.gradle and the PACKAGES comment line, the version specified under packages overrides the version assigned in the PACKAGES comment.

PACKAGES comment line in a playbook retrieved using the playbook provider

Packages declared in the PACKAGES comment line are added to any packages declared under the packages property in build.gradle.

If the same package is declared in both the PACKAGES comment line and build.gradle, the version in build.gradle takes precedence.

The PACKAGES comment is ignored if the playbook isn’t retrieved using the playbook provider feature.