Composite Projects
A composite project in Jmix refers to a project structure that organizes multiple related add-ons and applications into a single IDE project, even if they are located in different source code repositories.
Creating Composite Project
To create an empty composite project, start the project wizard and select the Composite Project template. Studio will create a project with the following structure (provided that the project name is sales
):
root-dir/ sales-all/ build.gradle settings.gradle
Then you can add subprojects by creating new add-ons or applications, checking out an existing project from VCS or just adding an existing folder with a project. Use New → Subproject actions of the Jmix Tool Window:
We recommend placing subprojects within the project’s root directory, alongside the <project-name>-all
aggregator project.
Studio shows the composite project and all subprojects as top-level nodes in the Jmix Tool Window:
As you can see, the aggregator composite project’s settings.gradle
file uses includeBuild
instructions. These instructions leverage Gradle’s composite build feature, which helps structure projects effectively.
In a composite build, Gradle replaces dependencies on artifacts with direct dependencies between subprojects. This means that changes made to an add-on immediately impact dependent add-ons and the application. IntelliJ IDEA perfectly imports such a project, recognizing the Gradle-defined dependencies. As a result, you get a composite project structure that enables transparent refactoring and eliminates the need for the "publish locally" workflow.
Opening Composite Project
When opening a composite project, make sure to navigate to the <project-name>-all
aggregator project directory and open the build.gradle
file within that directory:
Managing Properties
You can edit common properties of all subprojects. Click Settings→Project Properties on the toolbar of the Jmix Tool Window. Select All subprojects when Studio asks you which project you want to edit:
The common properties include the artifact repository settings and Jmix framework version. So, you can upgrade all subprojects to a newer Jmix version at once.
Configuring Dependencies
The most useful feature for large composite projects is the ability to configure dependencies between subprojects in a simple dialog.
You can open it from the Settings → Dependencies Between Subprojects action of the Jmix Tool Window.
Here customers is an add-on which depends on the users add-on. According to changes you make in this dialog, Studio adds artifact dependencies to build.gradle
files of the subprojects, and also configures the @JmixModule
annotations of the add-ons. It also prevents you from introducing circular dependencies. In the screenshot below you can see that the dialog doesn’t allow you to make the users add-on dependent on customers because customers already depends on users:
Managing Data Stores
Studio can generate Liquibase changelogs in add-ons, including when working with them in composite projects.
To generate a changelog, you first need to define a Data Store in the add-on. It will be displayed in the Jmix tree:
Its settings will be stored in the jmix-studio.xml
file instead of the Java configuration.
Now, you can execute the Generate Liquibase Changelog action on the Data Store.
In a composite project, you should specify a Data Store for the same add-on again, because the composite project has its own jmix-studio.xml
file located in the <project-name>-all
aggregator project. So, data store settings will be stored separately for when you are working on the add-on in a standalone project and in a composite project, but the set of generated changelogs will be the same.