Publish packages to Ballerina Central

The sections below include information about working with library packages.

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 the Ballerina.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/ directory tests/ directory, and the Module.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

1. Create an account on Ballerina Central. To register, visit the home page and log in via a Google or GitHub account.

2. Navigate to the Dashboard and acquire an access token.

3. Download and place the Settings.toml file in your home repository (<USER_HOME>/.ballerina/). If you already have a Settings.toml file configured in your home repository, follow the other option and copy the access token into the Settings.toml. If you are connected to the internet via an HTTP proxy, add the following section to Settings.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.