Runtime add-ons

Before you Start

🔥 This feature is currently considered experimental. Try it out and give feedback by reporting bugs and suggesting new features. It’s not recommended for production use.

💻 This feature is available to developers.

Sirius Web applications support loading additional features at runtime. Use add-ons to extend an existing deployment without rebuilding or repackaging the core application.

1. Add-on structure

An add-on is a Maven multi-module project that typically contains:

  • Backend services (backend/services/your-add-on-services)

  • View based representation descriptions (backend/views/your-add-on-view)

  • A distribution module that assembles the deployable artifact

Example top-level pom.xml snippet:

<project>
  <groupId>com.example.siriusweb</groupId>
  <artifactId>your-add-on</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>
  <modules>
    <module>backend/services/your-add-on-services</module>
    <module>backend/views/your-add-on-view</module>
    <module>distribution</module>
  </modules>
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <artifactId>maven-assembly-plugin</artifactId>
          <version>3.7.1</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Build the add-on with:

mvn clean package

The distribution module produces a JAR that bundles both backend and view contributions.

2. Deploying an add-on

  1. Copy the generated JAR to a folder accessible by your Sirius Web application, for example: bash cp distribution/target/your-add-on.jar distribution/src/main/resources/your-add-on

  2. Start the application with the extra classpath: bash java -cp your-application.jar \ -Dloader.path='file:your-add-on/' \ -Dloader.main=your.Application \ org.springframework.boot.loader.launch.PropertiesLauncher

  3. The add-on classes and view descriptions become available immediately. Restart the application when you update the add-on jar to pick up changes.

Follow the Spring Boot documentation for PropertiesLauncher to combine multiple add-ons or external configuration directories.

3. Override Sirius Web frontend in an add-on

Use this mechanism when an add-on provides a frontend that must replace the default Sirius Web frontend. Package the compiled frontend artifacts in a dedicated classpath directory in the add-on JAR, with index.html at its root. Do not name this directory static because it would collide with Sirius Web’s frontend resources. Use a name specific to your add-on, like your-add-on-static, to prevent clashes with other add-ons. Set the Spring Boot spring.web.resources.static-locations property to this directory:

spring.web.resources.static-locations=classpath:/your-add-on-static/

Note the trailing / that lets Sirius Web resolve index.html relative to the configured location.

If multiple add-ons provide a frontend, only the index.html from the first matching static location is used. When possible, combine their frontend contributions into a single complete frontend build before deployment. This is a known limitation on the support for frontend add-ons.

4. Best practices

  • Version your add-ons independently from the base application and document compatibility.

  • Keep add-ons modular: expose clear extension points so they can evolve without impacting core modules.

  • Automate packaging and publishing so teams can consume add-ons from an artifact repository.