Publib
A unified toolchain for publishing libraries to popular package managers (formally jsii-release)
Install / Use
/learn @cdklabs/PublibREADME
publib
Previously known as
jsii-release
A unified toolchain for publishing libraries to popular package managers.
Supports:
- npm
- PyPI
- NuGet
- Maven
- Go (GitHub)
Usage
This is an npm module. You can install it using yarn add publib or
npm install publib. In most cases it will be installed as a devDependency
in your package.json.
This tool expects to find a distribution directory (default name is dist)
which contains "ready-to-publish" artifacts for each package manager.
dist/js/*.tgz- npm tarballsdist/python/*.whl- Python wheelsdist/nuget/*.nupkg- Nuget packagesdist/java/**- Maven artifacts in local repository structuredist/go/**/go.mod- Go modules. Each subdirectory should have its own go.mod file.
Each publisher needs a set of environment variables with credentials as
described below (NPM_TOKEN, TWINE_PASSWORD etc).
Then:
publib
You can customize the distribution directory through publib DIR (the
default is dist)
This command will discover all the artifacts based on the above structure and will publish them to their respective package manager.
You can also execute individual publishers:
publib-mavenpublib-nugetpublib-npmpublib-pypipublib-golang
npm
Publishes all *.tgz files from DIR to npmjs, GitHub Packages or AWS CodeArtifact.
If AWS CodeArtifact is used as npm registry, a temporary npm authorization token is created using AWS CLI. Therefore, it is necessary to provide the necessary configuration settings, e.g. by passing access key ID and secret access key to this script.
Usage:
npx publib-npm [DIR]
DIR is a directory with npm tarballs (*.tgz). Default is dist/js.
Options (environment variables):
| Option | Required | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NPM_TOKEN | Optional | Registry authentication token (either npm.js publishing token or a GitHub personal access token), not used for AWS CodeArtifact |
| NPM_TRUSTED_PUBLISHER | Optional | Use a Trusted Publisher configuration to publish packages. Requires npm CLI version 11.5.1 or later. When set, NPM_TOKEN will be ignored. |
| NPM_REGISTRY | Optional | The registry URL (defaults to "registry.npmjs.org"). Use "npm.pkg.github.com" to publish to GitHub Packages. Use repository endpoint for AWS CodeAtifact, e.g. "my-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/". |
| NPM_DIST_TAG | Optional | Registers the published package with the given dist-tag (e.g. next, default is latest) |
| NPM_ACCESS_LEVEL | Optional | Publishes the package with the given access level (e.g. public, default is restricted for scoped packages and public for unscoped packages) |
| AWS_ACCESS_KEY_ID | Optional | If AWS CodeArtifact is used as registry, an AWS access key can be spedified. |
| AWS_SECRET_ACCESS_KEY | Optional | Secret access key that belongs to the AWS access key. |
| AWS_ROLE_TO_ASSUME | Optional | If AWS CodeArtifact is used as registry, an AWS role ARN to assume before authorizing. |
| DISABLE_HTTPS | Optional | Connect to the registry with HTTP instead of HTTPS (defaults to false). |
Maven
Publishes all Maven modules in the DIR to Maven Central.
[!IMPORTANT] Starting July 2025 you must switch over to the new Maven Central Publisher. Follow these steps:
- Log in to https://central.sonatype.com/ with your existing username and password.
- Under your account, click View Namespaces, then click Migrate Namespace for your target namespaces.
- Generate a new username and password on the new publisher using the Generate User Token feature.
- Configure
MAVEN_SERVER_ID=central-ossrh.- Unset any
MAVEN_ENDPOINT.- Configure the new
MAVEN_USERNAMEandMAVEN_PASSWORD.
If you are still on Nexus and you signed up at SonaType after February 2021, you
need to use this URL: https://s01.oss.sonatype.org
(announcement).
Usage:
npx publib-maven [DIR]
DIR is a directory with a local maven layout. Default is dist/java.
Options (environment variables):
The server type is selected using the MAVEN_SERVER_ID variable.
MAVEN_SERVER_ID=ossrh; this is currently the default but will stop working in July 2025. Publish to the old OSSRH Nexus server.MAVEN_SERVER_ID=central-ossrh; publish to the new Central Publishing platform using a service endpoint more-or-less compatible with the old OSSRH Nexus server. This is required to publish to Maven Central starting July 2025.MAVEN_SERVER_ID=<anything else>; publish to a custom Nexus server.
| Server | Option | Required | Description |
| -------------------- | --------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| (all) | MAVEN_SERVER_ID | Yes going forward | Either ossrh (default but deprecated), central-ossrh, or any other string for a custom Nexus server. |
| (all) | MAVEN_USERNAME and MAVEN_PASSWORD | Yes | Username and password for maven repository. For Maven Central, you will need to Create JIRA account and then request a new project. Read the OSSRH guide for more details. |
| (all) | MAVEN_DRYRUN | No
