Publish packages to Ballerina Central
The sections below include information about working with library packages.
Table of contents Expand all Collapse all
A package uses Ballerina library packages as dependencies. Use the bal new
command to create a library package.
Create a library package
Execute the bal new -t lib
command to create a new library package.
bal new --template lib hello
This will create the Ballerina.toml
file, the hello.bal
source file, the Package.md
, the resources/
, tests/
directories, and Module.md
.
For more information on these files, see Package layout.
> cd hello
> tree .
.
├── Ballerina.toml
├── Module.md
├── Package.md
├── hello.bal
├── resources
└── tests
└── lib_test.bal
2 directories, 5 files
- The
Ballerina.toml
file identifies the directory as a Ballerina package. You can edit theBallerina.toml
file to change the organization, name, and the version of the package. - The
Package.md
is required when you publish a package to a repository. You can edit the content to add a meaningful description about the package. - The
hello.bal
file,resources/
directorytests/
directory, and theModule.md
file belong to the default module of the package.
For more information on these files, see Package layout.
[package]
org = "user"
name = "hello"
version = "0.1.0"
[build-options]
observabilityIncluded = true
Execute the bal pack
command to generate the Ballerina archive.
bal pack
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.
Prepare for publishing
-
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.toml
file in your home repository (<USER_HOME>/.ballerina/
). If you already have aSettings.toml
file configured in your home repository, follow the other option and copy the access token into theSettings.toml
. If you are connected to the internet via an HTTP proxy, add the following section toSettings.toml
and change accordingly.
[proxy]
host = "localhost"
port = "3128"
username = ""
password = ""
Organizations
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 don’t have any organizations created, you can visit the organizations page to create one.
Also, organization names starting with ballerina
(e.g., ballerina
, ballerinax
, 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.
Publish the package
Now, that you are ready to publish, execute the command below to publish the package to Ballerina Central.
bal push
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.