The Ballerina Extension for Visual Studio Code
The Visual Studio Code Ballerina extension provides a set of rich language features along with an enhanced user experience.
It offers easy development, execution, debugging, and testing for the Ballerina programming language.
The Ballerina language possesses a bidirectional mapping between its syntaxes and the visual representation.
You can visualize the graphical representation of your Ballerina source further via the extension.
Setting up the Prerequisites
Before getting started, make sure you have installed the Visual Studio Code editor with version >= 1.67.0.
Installing the Ballerina Extension
Follow the steps below to install the Ballerina extension.
- Download and install Ballerina.
- Install the Ballerina VS Code Extension.
Tip: Alternatively, click
Ctrl + P or (
Cmd + P in macOS) to launch the VS Code Quick Open screen, and enter
ext install WSO2.ballerina to install the Ballerina VS Code Extension.
Open a Ballerina
.bal file or a project directory to activate the extension.
Info: When the extension is activated, you can see the
Ballerina SDK: <version> in the status bar at the bottom left corner.
Running Your First Ballerina Program
Follow the steps below to create a sample Ballerina program in VS Code.
- Click View in the menu bar of the editor, and click Command Palette.
Tip: You can use the shortcut methods
⌘ + ↑ + P on Mac and
Ctrl + Shift + P on Windows and Linux.
In the search bar, type
Show Examples, and click Ballerina: Show Examples.
Select the Hello World Main example.
Click on the Run code lens on the editor.
You just ran your first Ballerina program with a few clicks.
Tip: If you wish to debug further, you can either use the Debug code lens or see debugging guidelines below.
Click the Show Diagram button on the editor’s title bar to view the graphical representation of the program.
Source Code View
Code Completion & Snippets
The extension provides you with suggestions on variables, keywords, and code snippets of language constructs (such as functions, type definitions, services, iterable constructs, etc.)
Help via Hover
When hovering over a symbol name, you will be provided with quick information about the particular symbol. For example, when hovering over a function name, you will be prompted with the associated documentation.
When typing a function/method call expression, the signature help will show information such as the function/method call’s description and parameter information. Signature help will be triggered when typing the open parenthesis and comma.
Code formatting has the two options below.
- Formatting a selected range in the document
The diagnostics show you the syntax and semantic errors in the source code. Varieties of diagnostics such as errors and warnings will be shown. For a selected set of diagnostics, you can see the quick fixes. For example, the
variable assignment is required diagnostic will have two associated quick fixes to create a new variable and ignore the return value.
The Ballerina VS Code extension comes with built-in debugging capabilities so that you can seamlessly troubleshoot your applications at runtime.
It allows you to debug Ballerina programs, services, tests and also provides remote debugging capabilities out of the box.
Below are some of the key debugging features provided by the Ballerina language extension.
- Conditional Breakpoints
- Log Points (plain texts and string templates)
- Pause/Continue Instructions
- Step In/Out/Over Instructions
- Strand View
- Call Stack View
- Local and Global Variable View
- Expression Evaluation
For detailed documentation on initializing debug sessions, and using the debugging features and advanced configuration options, see Ballerina Debugging.
Go to Definition
For a symbol, this feature will navigate you to the definition of the particular symbol. For example, when invoking the
Go To Definition option from a function call expression, you will be navigated to the definition of the function. Apart from jumping to the definition, the peek definition will also be supported. The behavior will be the same not only for the constructs within the sources in the current project but also for external modules and standard libraries as well.
Find all References
Invoking the references on a symbol will prompt you with all the symbol references in the current project.
This feature allows you to rename symbols by renaming all the references of the particular symbol.
There are two types of code actions suggested based on the node at a given cursor position and based on the diagnostics at a given cursor position.
Create Variable Code Actions
The code action types below are available for creating a variable.
Create variable: Create a variable for an expression where the
Variable Assignment Required diagnostic is present.
Create variable and type guard: Create a type guard to handle the error gracefully when the
Variable assignment Required diagnostic is present.
Create variable and check error: Add a check expression when the
Variable assignment Required diagnostic is present.
Ignore return value: Ignore the return value with the
_ where the
Variable Assignment Required diagnostic is present.
Code Actions for Union Types
The code actions below are available for union-type variables.
Type guard variable: Type guard a variable if the variable is of the union type.
Add check error: Add a check statement when there is an error union.
Code Actions for Imports
The code actions below are available for imports.
Import a module: Add the import statement for a module, which has a reference without an import statement. This supports only the language library and the standard library.
Optimize imports: Optimize the import statements to remove unused imports and arrange the imports in alphabetical order.
Pull module: Pull locally unavailable Ballerina packages from the Ballerina Central repository.
Code Actions for Documentation
The code actions below are available for documentation.
Document this: Add the documentation to the top-level constructs, resources, and methods.
Document all: Document all the top-level constructs.
Update documentation: Update the existing documentation when parameters are missing or not documented. This depends on the warning diagnostics sent by the compiler.
Code Actions for Incompatible Types
The code actions below are available for incompatible types.
Change variable type: Change the type of a variable.
Add type cast: Add a type cast for the incompatible types.
Fix return type: Change the incompatible return type.
Change parameter type: Change the type of a function/ method parameter.
Code Actions for Create Functions
The code actions below are available for creating functions.
Create a function: Create a function using the selected variables/parameters.
Implement a method: Implement the selected method.
Documentation Code Lens
Document This code lens is shown for the public functions without documentation.
Run and Debug Code Lenses
Run and debug code lenses are shown for the entry points of the Ballerina project and its test cases. The entry points include the main function and the services within the default module of the project.
- Show Examples: It lists the available examples of the Ballerina language. By clicking on each example, you can explore each source code.
- Build: It provides quick access to build your Ballerina project. Once executed, the current Ballerina project relative to the currently-opened text editor is built using the
bal build CLI command.
- Pack: It is a quick access to pack your Ballerina library packages. Once executed, the current Ballerina project relative to the currently-opened text editor is packed using the
bal pack CLI command.
- Run: It runs your Ballerina project. Once executed, the opened Ballerina project is built using the
bal run CLI command.
- Test: It runs all the tests in your Ballerina project using the
bal test CLI command.
- Build Documentation: It is a quick guide to generate documentation for your Ballerina project. Once executed, the documentation is generated using the
bal doc CLI command. The generated documentation can be found inside the
apidocs directory in the
- Show Diagram: It is a palette reference to access the Diagrams. On execution, the diagram editor of the first diagram component listed under the Diagrams view is rendered.
- Add Module: It adds a Ballerina module for the given module name using the
bal add CLI command.
- Create 'Cloud.toml': It generates a
Cloud.toml file for your Ballerina project according to the default cloud specifications.
- Paste JSON as Record: This command converts a JSON string (that is copied to the clipboard) to a Ballerina record(s) and pastes it in your code.
Low Code View
Being based on sequence diagrams, Ballerina allows you to visualize a program written in Ballerina as a sequence diagram. The diagram displays the logic and network interaction of a function or a service resource making it easy to understand the source. You can view these diagrams using the Ballerina VS Code plugin.
Ballerina notebooks can be created in VS Code using the
.balnotebook extension for filename. Markdown and Ballerina code snippets are supported by Ballerina notebook cells.
Info: Make sure your VS Code version is
1.67.0 or higher when using Ballerina notebook.
Notebook cells can be executed using the Run button available at the left side of the cell or using
enter keys. Additionally
Execute Above Cells,
Execute Cell and Below,
Clear outputs of All Cells and
Restart Notebook actions are available through the user interface.
It is required to enable notebook debug mode to debug the notebook.
- Create Notebook: This command creates a notebook with the given filename.
- Code Lens - All: Enabled: It enables all code lens features and is enabled by default.
- Debug Log: It enables printing debug messages onto the Ballerina output channel and is disabled by default. These debug logs mainly include additional logs added for troubleshooting the extension.
- Ballerina: Trace Log: It enables printing trace messages onto the Ballerina output channel and is disabled by default. These trace logs mainly include the details of the requests sent from the extension to the Ballerina Language Server.
- Enable File Watcher: It enables watching file change events of the Ballerina project and is enabled by default.
- Ballerina: Enable Performance Forecast: It enables providing estimates on the performance of the services.
- Ballerina: Enable Semantic Highlighting: Semantic highlighting is enabled by default in the plugin. You have an option to disable this and rely on syntax highlighting.
- Enable Telemetry: It enables the Ballerina telemetry service and is enabled by default.
- Ballerina: Low Code Mode: This sets the low code as the default view of the plugin. Source code is the default view in a fresh installation.
- Home - It specifies the Ballerina home directory path and is only applicable if the Plugin - Dev: Mod is enabled.
- Ballerina: Plugin Dev Mode: It enables the plugin development mode and is disabled by default. If it is disabled, the extension picks up the Ballerina runtime installed in the environment. Also, if it is enabled, the extension picks up the Ballerina runtime defined in the Home configuration above.
- Enable Language Server Debug: It enables the Language Server debug mode and is disabled by default. It is only applicable if the Plugin Dev Mode is enabled.
- Enable Configurable Editor: It enables the configurable editor in code view when the run button flow is executed. By default, this is enabled only in the low code view.
- Enable Notebook Debug: It enables the notebook debug mode which provides a button in the dropdown near cell execution button, and is disabled by default.
For troubleshooting, see the Ballerina output. To view the Ballerina output tab, click View, click Output, and select Ballerina from the output list. It provides additional information if the plugin fails to detect a Ballerina distribution.
You can also enable debug logs from the Ballerina extension settings to view any issues arising from the extension features.
Ask for Help
Create Github issues to reach out to us.
By downloading and using the Visual Studio Code Ballerina extension, you agree to the license terms and privacy statement.
The VS Code Ballerina extension uses the following components, which are licensed separately.
- It runs with the support of the Ballerina Language Server, which is a part of the Ballerina language distribution. The Ballerina language is an open-source software that comes under the Apache License.
- It is structured as an extension pack along with the TOML Language Support extension.