skip to content

What is the [bundles] table for, and how do bundle entries relate to [libraries] aliases?

level: middleimportance: should knowfreq 45%

answer

  1. bundle = named array of library aliases
  2. applied with libs.bundles.<name>
  3. no version/coordinates of its own
  4. elements must be real [libraries] aliases
  5. all members hit the same configuration

basics

~10 s

A [bundles] entry is a named list of [libraries] aliases that are commonly used together, so you can add them all with one accessor instead of declaring each dependency separately.

solid answer

~40 s

The **[bundles]** table groups library aliases that are typically applied together into a single named accessor. Each entry is a TOML array of strings, where every string must be a **library alias** already declared in `[libraries]`: ```toml [bundles] testing = ["junit-jupiter", "mockito-core", "assertj-core"] ``` In a build script you then add the whole set at once: `testImplementation(libs.bundles.testing)`. This expands to all three dependencies. Bundles are pure convenience — they don't introduce versions or coordinates of their own; the versions still come from the referenced `[libraries]` entries (and their `version.ref`s). The main caveat: every name in a bundle must exactly match an existing library alias, or catalog generation fails.

code

kotlin · 4 lines
kotlin
dependencies {
    // expands to junit-jupiter + mockito-core + assertj-core
    testImplementation(libs.bundles.testing)
}

go deeper

for a junior

Know a bundle is a named list of dependencies applied together via libs.bundles.<name>.

for a middle

Explain that elements must be existing library aliases and that all members share one configuration.

for a senior

Advise on when bundling helps vs. when it artificially couples dependencies across modules.

for a principal

Standardize bundle definitions (testing, logging) across the org's shared catalog for consistency.

## Purpose of [bundles] A **bundle** is a named convenience grouping of dependencies you almost always add together — a testing stack, a logging stack, a web stack. Instead of listing each in your build script, you reference one bundle accessor. ## How it's wired Each `[bundles]` entry is a TOML array whose elements are **library aliases** (the keys you defined under `[libraries]`): ```toml [versions] junit = "5.10.2" [libraries] junit-jupiter = { module = "org.junit.jupiter:junit-jupiter", version.ref = "junit" } mockito-core = { module = "org.mockito:mockito-core", version = "5.11.0" } assertj-core = { module = "org.assertj:assertj-core", version = "3.25.3" } [bundles] testing = ["junit-jupiter", "mockito-core", "assertj-core"] ``` A bundle carries **no version and no coordinates of its own** — it is purely a list of pointers. Versions are resolved through each referenced library entry. The accessor `libs.bundles.testing` is generated automatically, mirroring the alias-to-accessor mapping rules (dashes become dots). ## Using it ```kotlin dependencies { testImplementation(libs.bundles.testing) } ``` This is equivalent to adding `libs.junit.jupiter`, `libs.mockito.core`, and `libs.assertj.core` individually. ## Validation and gotchas - Every element **must** be an existing `[libraries]` alias; an unknown name is a catalog error at generation time. - A bundle cannot reference another bundle — only libraries. - Because a bundle is applied to a single configuration call, all its members land in the **same** configuration (e.g. `testImplementation`). If two libraries belong in different configurations, don't bundle them together. - Bundles don't change resolution semantics; they're a readability/ergonomics feature only. ## When to use Use bundles for cohesive sets used identically across modules. Avoid forcing unrelated dependencies into a bundle just to shorten a script — that couples them artificially and makes per-module variation harder.

  • Can a bundle include a library alias that doesn't exist yet in [libraries]?
    No. Each bundle element must reference an already-declared [libraries] alias; an unknown alias makes catalog generation fail.
  • Do bundles let you mix configurations, e.g. some implementation and some testImplementation?
    No. A bundle is added through one configuration call, so every member lands in that same configuration. Split them into separate bundles if they belong in different configurations.

saying these in an interview costs you the question

  • Thinking bundles carry their own version — they only point to libraries.
  • Believing a bundle can reference another bundle.
  • Putting libraries that belong in different configurations into one bundle.

context

resolving links…