How-To Adding, Removing, or Moving Modules

This page provides step-by-step instructions for modifying an application's module composition — adding new modules, removing existing ones, managing dependencies, moving modules between applications, and splitting applications.

Adding a Module

To add a backend module, insert an entry into the modules array in application.template.json:

{
  "name": "mod-new-module",
  "version": "latest",
  "preRelease": "false"
}

To add a UI module, insert an entry into the uiModules array instead, using the folio_ prefix:

{
  "name": "folio_new-module",
  "version": "latest",
  "preRelease": "false"
}

After editing the template:

Commit and push the change to the target branch
The update scheduler runs within ~20 minutes and resolves the module version against the FOLIO Module Registry
The CI system validates module interface compatibility with other modules in the application
The resolved version appears in application.lock.json after a successful run

On pre-release branches, direct commits are typical. On release branches, creating a pull request for the template change is recommended — the merge queue validates and merges it through the standard flow. Use a semver constraint instead of "latest" on release branches (e.g., "^1.0.0").

Tip: When a module change affects multiple applications (e.g., adding a shared module), consider creating pull requests in each affected repository to coordinate the changes and allow review before the scheduler processes them.

Removing a Module

To remove a module, delete its entry from the modules or uiModules array in application.template.json.

Before removing, consider:

Whether other applications depend on interfaces provided by this module
Whether the module is required by any platform-level configuration

Commit and push the change. The CI validation (eureka-ci / validate-application) flags interface dependency conflicts if other modules in the application require interfaces that only the removed module provides.

If validation fails with dependency conflicts, coordinate with the maintainers of dependent applications before proceeding.

Adding an Application Dependency

If an application requires another application to be present (e.g., app-agreements requires app-licenses), add an entry to the dependencies array in application.template.json:

{
  "name": "app-licenses",
  "version": "^1.0.0",
  "preRelease": "false"
}

Version constraint guidelines for dependencies:

Use ^X.Y.Z to allow compatible updates within the major version
Match the major version of the target application's current release
On release branches, ensure the constraint matches the target application's release version

Version Management After Composition Changes

When the module composition of an application changes — whether modules are added, removed, or moved — the application version in pom.xml should be bumped to reflect the new composition. This applies to manual composition changes made directly on the branch (not to automated version-update PRs created by the scheduler, which handle versioning automatically).

If other applications declare a dependency on this application (in their dependencies array in application.template.json), the dependency version constraint in those applications should be updated to match the new version. This ensures that dependent applications resolve the correct application version — one that contains the updated module composition.

Example: If app-licenses changes its module composition and bumps from 1.0.0 to 1.1.0, then app-agreements (which depends on app-licenses) should update its dependency constraint:

{
  "name": "app-licenses",
  "version": "^1.1.0",
  "preRelease": "false"
}

Moving a Module Between Applications

Moving a module from one application to another requires coordinated changes across multiple repositories.

Version Uniqueness Constraint

The same module version cannot exist in two different applications simultaneously. Publishing duplicate module versions across applications fails platform-level validation. Therefore, a module move requires that the target application uses a new version of the module — one that does not already exist in the source application's published descriptor.

In practice, this means the module team must publish a new version before the move can be completed.

Step-by-Step Process

Coordinate the new module version — ensure the module team publishes a new release version that the target application will use
Remove the module from the source application — edit the source application's application.template.json and remove the module entry
Add the module to the target application — edit the target application's application.template.json and add the module entry with a version constraint that matches the new version
Update dependencies if needed — if the source application still needs interfaces from the moved module, add a dependency on the target application:

{
  "name": "app-target",
  "version": "^1.0.0",
  "preRelease": "false"
}

Wait for CI validation — ensure both applications pass eureka-ci / validate-application checks

Recommended Approach: Use Pull Requests

For module moves — especially those affecting multiple applications — creating pull requests rather than pushing directly to the branch is strongly recommended. This approach:

Allows review of the template changes before the scheduler processes them
Enables coordination of merge timing across repositories
Provides a clear audit trail of the change

On release branches, pull requests are created automatically by the scheduler when template changes are detected. Coordinate approval timing between the PRs in both repositories.

Splitting an Application

When an application needs to be reorganized or a subset of modules needs to be extracted into a new application:

Step-by-Step Process

Create a new application repository — follow the Creating a New Application Repository guide
Move modules to the new application — follow the "Moving a Module Between Applications" process above for each module being extracted. Remember the version uniqueness constraint — each module needs a new version for the target application
Add cross-application dependency — if the original application still needs the moved modules' interfaces, add a dependency on the new application in the original application's dependencies array
Add the new application to the platform — edit platform.template.json in the platform-lsp repository and add the new application entry. Creating a pull request for this change is recommended to allow review
Request environment inclusion — request that the new application be included in snapshot environments: Environment Inclusion Instructions

Changes on Release Branches

When modifying module composition on a release branch, the following differences apply:

Version constraints — use semver constraints instead of "latest" (e.g., "^2.0.0", "~2.1.0", "=2.1.3")
PR-based changes — template changes on release branches trigger pull request creation by the scheduler. The merge queue validates and merges the PR through the standard flow
Coordinated changes — for multi-application changes (moves, splits), coordinate PR approval timing across the affected repositories to minimize the window where applications are in an inconsistent state

Example — adding a module on a release branch:

{
  "name": "mod-new-module",
  "version": "^1.0.0",
  "preRelease": "false"
}

For the full PR-to-merge flow on release branches, see Managing Release Branch Updates.

Related Pages

Working with Application Repositories — overview of application repository structure and CI system
Understanding Application Repository Files — detailed reference for template files, configuration, and version constraints
Managing Release Branch Updates — the automated PR flow for release branches