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:

new subprojects

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:

composite projects structure

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:

open composite project

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:

composite project edit properties

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.

composite project dependencies

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:

composite project dependencies 2

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:

add on data store

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.