A package uses Ballerina library packages as dependencies. The sections below include information about working with library packages.
Create a library package
Execute the command below to create a new library package named
$ bal new --template lib hello
This creates the files below.
$ cd hello $ tree . . ├── Ballerina.toml ├── Module.md ├── Package.md ├── hello.bal ├── resources └── tests └── lib_test.bal 2 directories, 5 files
Ballerina.tomlfile identifies the directory as a Ballerina package. You can edit the
Ballerina.tomlfile to change the organization, name, and the version of the package.
Package.mdis required when you publish a package to a repository. You can edit the content to add a meaningful description about the package.
tests/directory, and the
Module.mdfile belong to the default module of the package.
For more information on these files, see Package layout.
To generate the Ballerina archive, execute the command below.
$ bal pack
You view the output below.
Compiling source user/hello:0.1.0 Creating bala target/bala/user-hello-any-0.1.0.bala
Publish a library package to Ballerina Central
You can publish a Ballerina archive to the Ballerina Central. Before you publish, ensure the package works as intended because a publish is permanent. Once published to Ballerina Central, you cannot overwrite the version or remove the package. However, the number of package versions you can push to Ballerina Central is not restricted.
Tip: As a precaution, use the local repository first to test out the functionality of the library package before publishing it to Ballerina Central.
Obtain an access token
Create an account on Ballerina Central. To register, visit the home page and log in via a Google or GitHub account.
Navigate to the Dashboard and acquire an access token.
Download and place the
Settings.tomlfile in your home repository (
<USER_HOME>/.ballerina/). If you already have a
Settings.tomlfile configured in your home repository, follow the other option and copy the access token into the
Configure proxy settings (optional)
If you are connected to the internet via an HTTP proxy, you need to configure it in the
Settings.toml file to carry out the Ballerina Central related operations such as publishing a package, pulling a package or resolving packages. Add the following section to
If your proxy does not require any credentials, keep username, password fields as empty as below.
Add necessary certificates to the truststore
If you encounter any certificate-related issues such as the one below when connecting via a proxy:
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target.
follow the steps below to trust the certificates associated with the proxy.
Navigate to the
dependencies/folder located in the Ballerina installation directory. Here, you should notice one or more Java Runtime Environment (JRE) instances.
Identify the certificates associated with the proxy. This information is typically found in the documentation provided by your proxy vendor.
Execute the below command in a command line with administrative privileges.
<BALLERINA_JRE>/bin/keytool.exe -import -trustcacerts -file <CERTS_PATH> -alias <ALIAS_NAME> -keystore <BALLERINA_JRE>/lib/security/cacerts
Note: If you are using multiple Ballerina distributions, you may need to follow the above steps to all the JRE instances individually for each distribution.
Define the organization
When you push a package to Ballerina Central, the organizations are validated against the value of the
org field defined in the Ballerina.toml file. Therefore, when you have more than one organization in Ballerina Central, pick the organization name that you intend to push the package into, set that as the
org in the
Ballerina.toml file inside the package directory, and rebuild the package. If you do not have any organizations created, you can visit the organizations page to create one.
Also, organization names starting with
ballerinai, etc.) are reserved for system use, and you cannot publish any packages starting with the
ballerina prefix to Ballerina Central. Therefore, if you have used a name pattern matching this, update the
Ballerina.toml and rebuild the package.
You can also choose who will have access to the package you are publishing by setting the package visibility in the
Ballerina.toml file. If you set the visibility as
private, it will only be visible and accessible to the members within the organization you are pushing the package into. Private packages will be visible on Ballerina Central only if you are logged in. Likewise, if you or a member of your organization wants to pull a private package, the
Settings.toml file needs to be set up according to the previous section (if not set up already).
Publish the package
Now, that you are ready to publish, execute the command below to publish the package to Ballerina Central.
$ bal push
Publish a new version of a package
If you require adding new features/improvements/fixes to a library package which you have already published to Ballerina central, you are allowed to publish them under a new version, based on the Semantic Versioning Specification. However, it's the library developer's responsibility to be cautious when deciding on the new package versions (especially when there are potential breaking/backward-incompatible API changes), as otherwise, it may result in library versions that are compatible only by the version but not by the implementation.
Tip: As a precaution, use the Ballerina semver validator CLI tool (experimental) to check if your new API changes conform to the version that you are trying to publish to Ballerina central.
By default, running the
bal semver command on the root directory of the package will compare the local changes with the
"closest compatible" published version available in Ballerina Central.
bal semver --help for the CLI help text which outlines all the available command options)
Note: Semver validator CLI support is only available from Swan Lake Update 2 onwards.
Use the packages in Ballerina Central
After publishing your first package, you can create a second package and use the already published package in it. Any package published in Ballerina Central is public and can be used in other packages. For more information, see Import a module.
Deprecate a published version of a package
If you have released a package version containing a critical bug or security vulnerability, it is possible to deprecate that specific version.
To deprecate a particular version of a package on Ballerina Central, the package owner can run the following command. An optional deprecation message can also be included, which will be displayed to current users of the package.
$ bal deprecate <org-name>/<package-name>:<version> --message <deprecation-message>
A deprecated package version will not appear in package searches on Ballerina Central or the CLI. Additionally, it will not be used for dependency resolution unless it is already a part of a sticky build or no other compatible package version exists. If the deprecated version is in use, a warning message containing the provided deprecation message will be shown during the project build.
To reverse the deprecation of a package, execute the same command with the
$ bal deprecate <org-name>/<package-name>:<version> --undo