8. ‘How-to’ guides
Prev Part III. Configuration Guide Next

8. ‘How-to’ guides

This section provides answers to some common ‘how do I do that…​’ type of questions that often arise when configuring Spring Initializr.

8.1 Add a new dependency

To add a new dependency, first identify the Maven co-ordinates of the dependency you want to add (groupId:artifactId:version) and then check which versions of Spring Boot it works with. If there are multiple versions that work with different versions of Spring Boot, then that’s fine too.

  • If there is a published BOM that manages the version of you dependency, then add that first, in the env section (see Section 7.5, “Configuring Bill of Materials”).
  • Then configure the dependency, fitting it into an existing group if you can, otherwise creating a new group.
  • If there is a BOM then omit the version.
  • If there is a Spring Boot version range (or min or max) that you need for this dependency, add that as a linked version.

8.2 Override the version of a dependency

Sometimes it happens that the BOM that normally manages your dependency version is in conflict with the newest version. Or maybe this is the case for only a range of Spring Boot versions. Or maybe there just is no BOM, or it’s not worth creating one for just one dependency. In these cases you can specify the version manually for a dependency either at the top level, or in a version mapping. At the top level it looks like this (just a version property in a dependency):

initializr:
  dependencies:
    - name: Tech
      content:
        - name: Acme
          id: acme
          groupId: com.example.acme
          artifactId: acme
          version: 1.2.0.RELEASE
          description: A solid description for this dependency

8.3 Link a Boot version to a version of your dependency

If your dependency requires a specific version of Spring Boot, ot different versions of Spring Boot require different versions of your dependency there are a couple of mechanisms to configure that.

The simplest is to put a versionRange in the dependency declaration. This is a range of versions of Spring Boot, not of your dependency. For example:

initializr:
  dependencies:
    - name: Stuff
      content:
        - name: Foo
          id: foo
          ...
          versionRange: 1.2.0.M1
        - name: Bar
          id: bar
          ...
          versionRange: "[1.5.0.RC1,2.0.0.M1)"

In this example Foo is available for Spring Boot 1.2.0 (or any milestone of 1.2.0) or greater, and Bar is available for Spring Boot 1.5.0 up to, but not including 2.0.0.

If different versions of your dependency work with different versions of Spring Boot, that’s when you need the mappings property. A mapping is a combination of a versionRange and some or all of the other properties of the dependency, overriding the values defined at the top level. For example:

initializr:
  dependencies:
    - name: Stuff
      content:
        - name: Foo
          id: foo
          groupId: org.acme.foo
          artifactId: foo-spring-boot-starter
          versionRange: 1.3.0.RELEASE
          bom: cloud-task-bom
          mappings:
            - versionRange: "[1.3.0.RELEASE,1.3.x.RELEASE]"
              artifactId: foo-starter
            - versionRange: "1.4.0.RELEASE"

In this example, The artifact of foo was changed to foo-spring-boot-starter as of the version that is compatible with Spring Boot 1.4. This mapping instruct that if Spring Boot 1.3.x is selected, the artifact Id should be set to foo-starter.

A mapping can also be applied to a BOM declaration. For example:

initializr:
  env:
    boms:
      my-api-bom:
        groupId: org.acme
        artifactId: my-api-bom
        additionalBoms: ['my-api-dependencies-bom']
        mappings:
          - versionRange: "[1.0.0.RELEASE,1.1.6.RELEASE)"
            version: 1.0.0.RELEASE
            repositories: my-api-repo-1
          - versionRange: "1.2.1.RELEASE"
            version: 2.0.0.RELEASE
            repositories: my-api-repo-2

In this example Spring Boot versions up to 1.1.6 select version 1.0.0 of the BOM, and set a different repository. Spring Boot versions 1.2.1 and above select 2.0.0 of the BOM and yet another repository.

8.4 Configure a snapshot repository

A dependency, or a BOM, might require the use of a specific repository, if the default one (usually Maven Central) does not contain the artifacts. Normally, the best place to declare that is in the BOM configuration, but if there isn’t a BOM then you can put it in the dependency itself. You can also use a Spring Boot version mapping to override the default repository for a dependency or BOM.

8.5 Make sure a regular dependency brings the base starter

If a dependency does not stand on its own (and specifically if it does not depend on an existing Spring Boot starter) you can flag it as a "non starter":

initializr:
  dependencies:
    - name: Stuff
      content:
        - name: Lib
          id: lib
          groupId: com.acme
          artifactId: lib
          starter:false

When a project is generated that only has dependencies with this flag set, then the base Spring Boot starter is added as well.

8.6 Share common dependency settings in a group

A dependency group is a hint for user interface implementations, to group things together for users when they are selecting dependencies. It is also a convenient way to share settings between dependencies because every dependency inherits all the settings. The most common settings in a group are the groupId, versionRange and bom:

initializr:
  dependencies:
    - name: Stuff
      bom: stuff-bom
      versionRange: "[1.3.0.RELEASE,2.0.0.M1)"
      content:
...

These dependencies, by default, will be available only for Spring Boot versions 1.3 up to 2.0 (excluded) and will bring in the stuff-bom BOM.

Prev Up Next
7. Creating your own instance Home 9. Advanced configuration