This guide provides detailed instructions on how to configure your Liberty project to use the Liberty Tools for Visual Studio Code extension. For information regarding known issues and limitations, refer to our Common Issues wiki page or our Known Problems and Limitations wiki page.
- Before you begin
- Open the Liberty dashboard
- Run your application on Liberty using dev mode
- Run your application tests
- View your application test reports
- Stop your application
- Debug your application
- Manually add your liberty project to the dashboard
- Configure a Liberty server
- Develop with Jakarta EE and MicroProfile APIs
- Visual Studio Code 1.78.0 or later.
- Java 17 or later is required by Liberty Tools for Visual Studio Code. To point Visual Studio Code to a specific runtime, see Settings for more information.
-
Define a Liberty
server.xmlconfiguration file in thesrc/main/liberty/configlocation. -
Configure the Liberty Maven Plugin or configure the Liberty Gradle Plugin. We recommend using the most recent versions of the plugins as they include several important bug fixes.
Liberty Tools for Visual Studio Code requires Java 17 or later to ensure that the following language servers start properly:
A toast message alerts you if any language server fails to run or if Visual Studio Code has trouble locating your Java.
To resolve this issue, you can define settings in your Visual Studio Code settings.json file or set system environment variables to point Liberty Tools to Java 17 or later.
For both Liberty Config Language Server and Eclipse Language Server for Jakarta EE, Liberty Tools for Visual Studio Code will check for the Java versions in the following order:
java.jdt.ls.java.homein settings.json- The embedded JRE included by Language Support for Java(TM) by Red Hat.
JDK_HOMEorJAVA_HOMEas system environment variables. (Note: if bothJDK_HOMEandJAVA_HOMEare set,JDK_HOMEwill take precedence)
By default, Liberty Tools installs the latest version of the Language Support for Java(TM) by Red Hat extension. The latest version contains an embedded JRE higher than Java 17 and therefore no additional configuration is required. However, if using an older version of the Language Support for Java(TM) by Red Hat extension or using the universal version without the embedded JRE causes an issue, then java.jdt.ls.java.home or one of JDK_HOME or JAVA_HOME must be configured to use Java 17 or later.
For LemMinX, Liberty Tools for Visual Studio Code will check for the Java versions in the following order:
xml.java.homein settings.jsonJDK_HOMEorJAVA_HOMEas system environment variables. (Note: if bothJDK_HOMEandJAVA_HOMEare set,JDK_HOMEtakes precedence)
| Setting | Description | Provided By |
|---|---|---|
maven.executable.path |
Maven commands executed by dev mode honour this setting. When this value is empty, dev mode tries to use mvn or mvnw according to the value of maven.executable.preferMavenWrapper. |
Maven for Java extension |
maven.executable.preferMavenWrapper |
Maven commands executed by dev mode honour this setting. If this setting set to true, dev mode tries to use mvnw if a Maven wrapper file can be found. Otherwise, it uses mvn. |
Maven for Java extension |
java.import.gradle.wrapper.enabled |
Gradle commands executed by dev mode honour this setting. If this setting is set to true, dev mode tries to use gradlew if a Gradle wrapper file can be found. Otherwise, it uses gradle. |
Language support for Java extension |
xml.java.home |
This setting allows a user to define their LemMinX language server runtime without altering the JAVA_HOME environment variable. |
Not set |
java.jdt.ls.java.home |
This setting specifies the folder path to the JDK (17 or later) that is used to launch the Java Language Server. This setting replaces the Java extension's embedded JRE to start the language servers. | Not set |
By default, the Liberty dashboard appears in the Project Explorer side bar. Optionally, you can drag the Liberty dashboard into the Activity Bar.
| Side Bar view | Activity Bar view |
|---|---|
 |
 |
Projects that are already properly configured to run on Liberty and use Liberty dev mode are automatically added the Liberty dashboard when it opens. If your Liberty project does not show up in the Liberty dashboard automatically and you have the Liberty Maven or Liberty Gradle plugin configured, check out how to manually add your project to the Liberty dashboard.
If you add new projects or make changes, use the refresh icon in the Liberty dashboard toolbar to refresh the dashboard view.
The following three menu actions are available to start your Liberty application in dev mode through the Liberty dashboard or the Visual Studio Code command palette:
- Start your application in dev mode
- Start your application in dev mode with configuration
- Start your application in dev mode in a container
The Liberty dashboard provides a context menu for Liberty projects. You can choose different commands from the menu to speed up application development.
The Liberty Tools plugin provides a set of commands to the command palette. The command palette is accessible a number of ways. Additionally, the Shift + Alt + L shortcut shows a similar menu with only Liberty commands.
All Liberty Tools commands that are described in the following sections are also available from the command palette.
To start your application in dev mode, select the Start command for your application in the Liberty dashboard.
A new terminal tab opens to run the application in dev mode.
To start your application in dev mode with custom configuration, select the Start... command for your application in the Liberty dashboard. The command opens an edit dialog where you can specify parameters for the Liberty Maven dev goal or Liberty Gradle dev task.
A new terminal tab opens to run the application in dev mode.
The next time you choose to start dev mode with configuration, the menu provides a history of previously used configurations.
To use dev mode for containers, select the Start in container command for your application in the Liberty dashboard.
For more information on dev mode for containers, check out the Liberty Maven devc goal or the Liberty Gradle libertyDevc task.
After your application is running on Liberty using dev mode, you can easily run the tests provided by your application.
To run tests, select the Run tests command for your application in the Liberty dashboard.
The tests are run in the corresponding terminal.
After you finish running your application tests, you can access the produced test reports.
To view the integration test report for Maven-built applications, select the View integration test report command for your application in the Liberty dashboard.
This command looks for the integration test report at the /target/site/failsafe-report.html default location.
To view the unit test report for Maven-built applications, select the View unit test report command for your application in the Liberty dashboard.
This command looks for the unit test report at the/target/site/surefire-report.html default location.
To view the test report for Gradle-built applications, select the View test report command for your application in the Liberty dashboard.
This command looks for the test report at the build/reports/tests/test/index.html default location.
To stop your application, select the Stop command for your application in the Liberty dashboard.
To attach the debugger, you must have a running server. Once the server is running, click the Attach debugger command or select the Liberty: Attach debugger command in the command palette, followed by your application.
When the debugger is attached, the Visual Studio Code debug options become available.
In the event that your Liberty project is not automatically detected by the Liberty dashboard, you can manually add your Liberty project to the Liberty dashboard. To manually add your Liberty project to the Liberty dashboard, right-click into an empty space in the project explorer and select Add project to Liberty Dashboard or select the Liberty: Add project to the tool window command in the command palette, followed by your application.
You are prompted with a list of projects that are not already displayed in the in the Liberty dashboard.
To remove manually added Liberty projects from the Liberty dashboard, right-click in an empty space in the project explorer and select Remove project from Liberty Dashboard or select the Liberty: Remove project from the tool window command in the command palette, followed by your application.
Liberty configuration assistance provides editing assistance, such as code completion, diagnostics, and quick-fixes, in Liberty server.xml, server.env, and bootstrap.properties files.
- Start the project in dev mode by using one of the previously described Liberty dashboard or command palette commands. Dev mode installs the Liberty features that are required for your application.
- Open any of the supported Liberty configuration files.
- To use Liberty-specific code completion, press Ctrl + Space / Cmd + Space anywhere within the document. A drop-down list of completion suggestions appears.
Liberty configuration assistance is offered through the Liberty Config Language Server. For more information, see the project documentation in GitHub.
Liberty Tools editing assistance provides code completion, diagnostics, and quick-fixes in configuration and application files for Jakarta EE and MicroProfile APIs.
- Open a Java or microprofile-config.properties file.
- To use Jakarta EE-specific and MicroProfile-specific code completion, press Ctrl + Space / Cmd + Space anywhere within the document. A drop-down list of completion suggestions appears.
- To use Jakarta EE-specific and MicroProfile-specific quick-fixes, hover over a Jakarta EE or MicroProfile diagnostic. A pop-up dialog appears that contains the diagnostic message and a Quick Fix link, if a quick-fix is available. Click the Quick Fix... link to view a list of quick-fix options.
Jakarta EE API configuration assistance is offered through Eclipse LSP4Jakarta, the Language Server for Jakarta EE. For more information, see the project documentation in GitHub.
MicroProfile EE API configuration assistance is offered through Eclipse LSP4MP, the Language Server for MicroProfile. For more information, see the project documentation in GitHub.