# Spring Modulith

[Spring Modulith](https://spring.io/projects/spring-modulith) is a Spring project that helps developers build well-structured, modular [Spring Boot](https://spring.io/projects/spring-boot) applications.

Spring Modulith provides tools and best practices for creating domain-driven, modular monoliths. This approach simplifies the development of large, complex applications without the adoption of microservices architecture from the start of development.

Procedure: Enable the Spring Modulith plugin

This functionality relies on the [Spring Modulith](https://plugins.jetbrains.com/plugin/28733-spring-modulith)  plugin, which  is bundled and enabled in IntelliJ IDEA   by default. If the relevant features are not available, make sure that you did not disable the plugin.

1. Press `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) to open settings and then select `Plugins`.

2. Open the Installed tab, find the Spring Modulith plugin, and select the checkbox next to the plugin name.

Procedure: Add the Spring Modulith dependency to a new project

You can add the Spring Modulith dependency when you create a new project with the [Spring Boot project wizard](spring-initializr-project-wizard.html).

1. In the main menu, go to `File | New | Project…`, then select Spring Boot from the Generators list.

2. Configure the [basic project settings](spring-initializr-project-wizard.html#step-1-basic-project-configuration) and click Next.

3. In the Dependencies list, find and select Spring Modulith, then click Create.

## Structure of a modular application

A Spring Modulith application usually consists of:

* A main package with a class that is used to run the application. This class is annotated with `@SpringBootApplication` and usually has the `main(…)` method used to run it.

* Application modules — direct sub-packages of the main package that have: * Provided interface: an API made available to other modules, typically implemented using Spring beans and domain events published by the module. * Internal implementation components: intended for internal use within the module, not accessible from outside. * Required interface: a module's use of other modules' features, like calling their Spring beans, listening to their events, or using their exposed configuration properties.

Here is an example arrangement of a simple application:

```MARKDOWN
Demo
╰─ src/main/java
    ╰─ bookstore                           // main package
       ╰─ BookstoreMainApplication.java
       ╰─ catalog                          // application module package
           ╰─ ProductApi.java              // provided interface
           ╰─ domain
               ╰─ ProductService.java      // internal component
       ╰─ common
       ╰─ orders
           ╰─ web
               ╰─ OrderRestController.java // ProductApi is required interface
       ╰─ config
```

`OrderRestController.java` from the `orders` module here has a dependency on the exposed `ProductApi.java` from the `catalog` module.

> **Tip:**
> Check the official [Spring Modulith documentation](https://docs.spring.io/spring-modulith/reference/index.html) for more details.

In IntelliJ IDEA, as soon as you open the Project tool window `Alt+1` (Windows), `⌘ 1` (macOS), `⌘ 1` (IntelliJ IDEA Classic (macOS)), `⌘ 1` (macOS System Shortcuts), `Alt+1` (XWin), `Alt+1` (GNOME), `Alt+1` (KDE), `Alt+1` (Emacs), `Alt+1` (Sublime Text), `⌘ 1` (Sublime Text (macOS)), `Ctrl+1` (NetBeans), `Ctrl+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS)), you can review the structure of your modular application and navigate between its parts.

In the picture below, there is a modular application with top-level modules marked by a green lock and internal components marked by a red lock.

![Project with open and closed modules](https://resources.jetbrains.com.cn/help/img/idea/2026.2/open_and_closed_modules.png)

Also, you can inspect the [logical structure](viewing-structure-of-a-source-file.html#logical-structure) of the application from the framework's point of view: select the main application class that is annotated with `@SpringBootApplication` and press `Alt+7` (Windows), `⌘ 7` (macOS), `⌘ 7` (IntelliJ IDEA Classic (macOS)), `⌘ 7` (macOS System Shortcuts), `Alt+7` (XWin), `Alt+7` (GNOME), `Alt+7` (KDE), `Alt+7` (Emacs), `Alt+7` (Sublime Text), `⌘ 7` (Sublime Text (macOS)), `Ctrl+7` (NetBeans), `Ctrl+Alt+F` (Visual Studio), `⌃ ⌥ F` (Visual Studio (macOS)), `Alt+7` (Eclipse), `⌘ 7` (Eclipse (macOS)) (or go to `View | Tool Windows | Structure` in the main menu).

![List of the application's modules in the Structure tool window](https://resources.jetbrains.com.cn/help/img/idea/2026.2/modular_application_structure.png)

The Modulith-specific ![](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app-client.expui.objectBrowser.flattenModules.svg) Modules node shows the list of application's modules, their IDs, allowed dependencies, and named interfaces.

## Apply the Spring Modulith's guidelines

IntelliJ IDEA helps maintain your application's structure in line with Spring Modulith's architectural principles by providing a set of [inspections](code-inspection.html) and [quick-fixes](intention-actions.html). By default, these inspections have the severity level of an error, but the highlighted code does not cause neither compilation nor runtime errors. These issues will fail Modulith-specific tests only.

> **Tip:**
> In the 1.4.x version, Spring Modulith does not enforce developers to follow the modular structure principles.
>
>
>
> However, [starting with version 2.0.0](https://github.com/spring-projects/spring-modulith/issues/1287), you can enable strict structure verification by setting the `spring.modulith.runtime.verification-enabled` flag to `true` for the `spring-modulith-runtime` artefact.
>
>
>
> You can also [change the severity](configuring-inspection-severities.html) of IntelliJ IDEA's inspections in `Settings | Editor | Inspections | Spring Modulith`.

When implementing an application with Spring, developers may need to inject various Spring beans into other beans. IntelliJ IDEA helps with this by providing [a bean autocompletion feature](spring-support-tutorial.html#quickly_inject_beans).

For Spring Modulith, this feature has been adjusted. If an injection violates the application's module boundaries, you will see the warning icon in the completion popup.

![Import bean from another module](https://resources.jetbrains.com.cn/help/img/idea/2026.2/modulith_import_bean.png)

For the existing code, IntelliJ IDEA highlights bean usages that break the Spring Modulith rules and suggests quick-fixes that will refactor your code to align with the modular structure (invoked by clicking ![the Quick-fix icon](https://resources.jetbrains.com.cn/help/img/idea/2026.2/app-client.expui.codeInsight.quickfixBulb.svg) or pressing `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (NetBeans), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS))).

![Quick-fixes for an imported bean](https://resources.jetbrains.com.cn/help/img/idea/2026.2/modulith_quick_fix.png)

Depending on your architectural guides, you can select from the following quick-fixes:

* Move the component from the original module to the base package. ![Move a Java class to the base package](https://resources.jetbrains.com.cn/help/img/idea/2026.2/move_component.png)

* Annotate the injected class with [@NamedInterface](https://docs.spring.io/spring-modulith/reference/fundamentals.html#modules.named-interfaces) to open this class for other modules. ![A class with the added @NamedInterface annotation](https://resources.jetbrains.com.cn/help/img/idea/2026.2/namedInterface_annotation.png)

* Open the module that contains this class. The quick-fix creates a `package-info.java` file with the `@ApplicationModule` annotation for the module that contains the class you want to import. The module is marked as `OPEN`. ![An open module](https://resources.jetbrains.com.cn/help/img/idea/2026.2/module_now_open.png)

## Work with application module dependencies

When we specify intermodule dependencies, IntelliJ IDEA provides name completion and validation for modules, as well as navigation between them.

Procedure:

1. To add a dependency from one module to others explicitly, we need to modify the `package-info.java` file in the module that requires the dependency.

For example, to make the `orders` module depend on the `catalog` and `common` modules, we need to modify the `package-info.java` file located in the `orders` module.

![Module dependency scheme](https://resources.jetbrains.com.cn/help/img/idea/2026.2/module_dependency.png)

2. In the `package-info.java` file, place the caret inside the quotation marks in `allowedDependencies = {""}` and press `Ctrl+Space` (Windows), `⌃ Space` (macOS), `⌃ Space` (IntelliJ IDEA Classic (macOS)), `⌃ Space` (macOS System Shortcuts), `Ctrl+Space` (XWin), `Ctrl+Space` (GNOME), `Ctrl+Space` (KDE), `Alt+/` (Emacs), `Ctrl+Space` (Sublime Text), `⌃ Space` (Sublime Text (macOS)), `Ctrl+Space` (NetBeans), `Ctrl+Space` (Visual Studio), `⌃ Space` (Visual Studio (macOS)), `Ctrl+Space` (Eclipse), `⌃ Space` (Eclipse (macOS)) or start typing the module's name.

3. IntelliJ IDEA shows available module dependencies in the completion popup:

* `module` — a dependency on the entire module.

* `module :: interface` — a dependency on a specific named interface provided by the module.

* `module :: *` — a dependency on all interfaces provided by the module.

![Completion popup with allowed dependencies](https://resources.jetbrains.com.cn/help/img/idea/2026.2/add_dependency.png)

Select the one you want to add and press `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (NetBeans), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (Eclipse), `⏎` (Eclipse (macOS)).

> **Note:**
> `allowedDependencies = {}` acts as an allowlist.
>
>
>
> When the braces are empty (`{}`), no dependencies are allowed. When specific modules are listed, then only those modules are allowed to be used.

4. You can navigate to an added module by clicking it and pressing `Ctrl+B` (Windows), `⌘ B` (macOS), `⌘ B` (IntelliJ IDEA Classic (macOS)), `⌘ B` (macOS System Shortcuts), `Ctrl+B` (XWin), `Ctrl+B` (GNOME), `Ctrl+B` (KDE), `Ctrl+Alt+G` (Emacs), `F12` (Sublime Text), `F12` (Sublime Text (macOS)), `Ctrl+B` (NetBeans), `F12` (Visual Studio), `F12` (Visual Studio (macOS)), `F3` (Eclipse), `F3` (Eclipse (macOS)).

The module gets selected in the Project tool window `Alt+1` (Windows), `⌘ 1` (macOS), `⌘ 1` (IntelliJ IDEA Classic (macOS)), `⌘ 1` (macOS System Shortcuts), `Alt+1` (XWin), `Alt+1` (GNOME), `Alt+1` (KDE), `Alt+1` (Emacs), `Alt+1` (Sublime Text), `⌘ 1` (Sublime Text (macOS)), `Ctrl+1` (NetBeans), `Ctrl+Alt+L` (Visual Studio), `⌘ ⌥ L` (Visual Studio (macOS)), `Alt+1` (Eclipse), `Alt+1` (Eclipse (macOS)).

![A selected module in the Project tool window](https://resources.jetbrains.com.cn/help/img/idea/2026.2/module_navigation.png)

5. If a module listed as a dependency does not exist, IntelliJ IDEA will highlight the reference, allowing you to fix the application's structure to prevent a startup failure.

![Module does not exist](https://resources.jetbrains.com.cn/help/img/idea/2026.2/name_validation.png)