Structuring Ballerina Code

The below are everything you need to know about using Ballerina packages to structure your code. It also introduces the package-related commands in the `bal` command-line tool.

Organizing Your Code

There are two ways to write your code in a Ballerina program:

  1. In a single Ballerina source file (with the .bal extension)
  2. In a Ballerina package

The single source file program is a quick and easy way to get started with Ballerina. However, when your code grows, you often want to:

  • organize your code by splitting it into multiple files
  • hide implementation-related parts from the API
  • manage your dependencies to achieve reproducible builds
  • write test cases to validate the functionality

Otherwise, you will end up with a messy, unstructured codebase, which is hard to navigate and understand. Therefore, code organization plays a significant role in improving readability, and thereby, writing a Ballerina package is the first step towards organizing code in Ballerina.

Working with Ballerina Packages

A Ballerina package organizes Ballerina code providing a unique namespace for all the functions, types, variables, and constants defined within the package. In Ballerina, how you package and distribute Ballerina code is also via packages.

A package has an organization name, package name, and a version, which are used to identify a package uniquely. The organization typically represents a user. It allows you to group all your packages. Both the organization and package names have to be valid Ballerina identifiers. Package versions have to be semantic as described in the SemVer specification.

A Ballerina package is stored in a directory. It contains a collection of source (.bal) files and a package manifest (Ballerina.toml file). The manifest file marks a directory as a Ballerina package.

Writing Your First Ballerina Package

Follow the steps below to write a simple program in a Ballerina package, which prints Hello World! in the console.

  1. Get Ballerina installed.

  2. In the CLI, execute the bal new helloworld command to create a new Ballerina package.

    This generates a package directory with the structure below.

     ├── Ballerina.toml
     └── main.bal
     0 directories, 2 files

    The Ballerina.toml File

    This file identifies a directory as a Ballerina package. It will include the content below.

     org = "examples"
     name = "helloworld"
     version = "0.1.0"
     observabilityIncluded = true

    The [package] table contains metadata about the generated package. The package name is helloworld and its current 0.1.0 version is in the examples organization.

    The main.bal File

    This file generated by the bal new command will have the content below.

     import ballerina/io;
     public function main() {
         io:println("Hello World!");

    This function prints “Hello World!” in the console.

  3. Execute the bal build command to build an executable of this file. You view the output below.

     Compiling source
     Running Tests
         No tests found
     Creating the BALA file
     Generating executable
  4. Execute the bal run command to run the program. You view the output below.

    $ bal run target/bin/helloworld.jar
     Hello World!

Note: You can have one or more Ballerina source files with the .bal extension at the root of your package directory. The variables, functions, types, and constants defined in one source file are visible to other files in the same directory because they are in the same namespace.

Working with Ballerina Modules

Now, that you successfully built and executed a Ballerina package, next, see Ballerina modules.