skip to content

In a Swift package target that bundles resources, how does its code load them through Bundle.module, and why does Bundle.main miss them?

level: middleimportance: should knowfreq 48%

answer

  1. a bundle per module
  2. generated, not written by you
  3. internal to the target
  4. the main bundle is the app's
  5. bundle: .module

basics

~20 s

SwiftPM puts a target's resources in their own bundle and generates an internal Bundle.module accessor for that module. Package code loads files and assets through Bundle.module; Bundle.main is the app's bundle, which does not hold them.

solid answer

~40 s

From tools version 5.3 a package target can carry resources. When it does, SwiftPM builds a **separate resource bundle** for that module and generates an `internal` static extension, `Bundle.module`, that locates it. Code in the target writes `Bundle.module.url(forResource:withExtension:)`, and SwiftUI lookups pass `bundle: .module` — `Image("badge", bundle: .module)`, `Color("BrandAccent", bundle: .module)`, `Text("title", bundle: .module)` — because with no bundle they search the app's main bundle. `Bundle.main` is the app (or the test runner), not the package's bundle, so lookups there return `nil`. The accessor is internal, so the app cannot write `Bundle.module` for a package; the package exposes a public API that loads the resource. SwiftPM's documentation says never to assume where the bundle sits on disk.

code

swift · 20 lines
swift
import Foundation
import SwiftUI

public enum Palette {
    // SwiftPM generates Bundle.module for this target because it declares
    // resources; the accessor is internal to this module.
    public static var paletteURL: URL? {
        Bundle.module.url(forResource: "palette", withExtension: "json")
    }
}

public struct BrandBadge: View {
    public init() {}

    public var body: some View {
        // Without bundle: .module these lookups search the app's main bundle.
        Image("badge", bundle: .module)
            .foregroundStyle(Color("BrandAccent", bundle: .module))
    }
}

go deeper

for a junior

Remember that package resources live in their own bundle and that package code reaches them with Bundle.module, not Bundle.main.

for a middle

Explain that SwiftPM generates an internal Bundle.module per module with resources, why default-bundle APIs such as Image and Text miss package assets, and how the app gets access.

for a senior

When a screen moves into a package and assets or translations vanish, find every default-bundle lookup, add bundle: .module, and expose loaders instead of bundle paths.

for a principal

Decide where shared resources live — one design-system target that exposes them or copies per feature — and make public loader APIs, not resource names, the contract.

## Resources in a package live in their own bundle From `// swift-tools-version: 5.3` a Swift package target can contain **resources**: JSON fixtures, asset catalogs, storyboards, localized strings, sounds. Files in the target's source folder that SwiftPM does not treat as source are resources scoped to that target; types that the build does not handle automatically must be declared in the target's `resources` list (with the process or copy rule — the manifest lesson covers that choice) or listed in `exclude`, and SwiftPM warns about files it does not recognize. When an app links the package, Xcode adds the package's code **and its resources** to the app. The resources do not land loose in the app's main bundle: each module that has resources gets its own **resource bundle**. In a `swift build` of a package named `Features`, the `DesignSystem` target's files end up in `Features_DesignSystem.bundle`. That name is a build detail, not an API — SwiftPM's documentation is explicit that a package should not make assumptions about where a resource is. ## Bundle.module: the generated accessor For each module that includes resources, SwiftPM generates a static extension on `Bundle` named `module`: ```swift let url = Bundle.module.url(forResource: "palette", withExtension: "json") ``` Three properties of this accessor explain most interview follow-ups: - **It is generated, and only for targets with resources.** A target with no resources has no `Bundle.module` of its own. - **It is internal.** Code in another module — the app target, or another target in the same package — cannot use it. Compiling `Bundle.module` in a module that only imports a resource-owning target fails with ``'module' is inaccessible due to 'internal' protection level``. - **It is per module.** `DesignSystem`'s `Bundle.module` and `Checkout`'s `Bundle.module` are different bundles. ## Why Bundle.main returns nil `Bundle.main` is the bundle of the running executable: the app on a device, or the test runner during `swift test`. The package's resources sit in a different bundle, so `Bundle.main.url(forResource: "palette", withExtension: "json")` returns `nil` even though the file shipped. The same trap hides in APIs that take an optional bundle and **default to the main bundle**: | Call inside the package | Where it looks | Result | |---|---|---| | `Image("badge")` | the app's main bundle | missing image | | `Image("badge", bundle: .module)` | the module's resource bundle | found | | `Color("BrandAccent")` | the app's main bundle | missing color | | `Text("title")` | the default strings table in the main bundle | untranslated key | | `Text("title", bundle: .module)` | the module's resource bundle | localized string | So the rule when moving a screen into a package is mechanical: every resource lookup that relied on the default bundle gains `bundle: .module`. ## Giving the app access Because `Bundle.module` is internal, the package decides what the app may reach. SwiftPM's documentation suggests exposing a public constant; in practice the cleanest shape is a public API that does the loading: 1. Keep the resource in the target that owns it. 2. Load it inside that target through `Bundle.module`. 3. Expose a `public` property, function or view — `Palette.paletteURL`, `BrandBadge()` — instead of handing out the bundle. That keeps resource names an implementation detail of the package and lets the package reorganize its files without breaking the app. ## Test fixtures and localized strings The same mechanism serves tests. A `testTarget` accepts `resources` too, so JSON fixtures for a decoder test live in the test target's folder and load through that test module's own `Bundle.module` — not through the bundle of the target under test, and not through `Bundle.main`, which during `swift test` is the test runner. Localized strings follow the module as well: a package screen that moves out of the app keeps its translations only if its string catalog or `.lproj` folders move into the target and every `Text` or `String` lookup names `bundle: .module`. A translation that silently falls back to its key after a refactor is almost always a lookup still aimed at the main bundle. ## Common mistakes - Looking a package's file up with `Bundle.main` and concluding the resource was not copied. - Writing `Image("logo")` in a package view and seeing an empty image in the app. - Hard-coding a path such as `Bundle.main.bundlePath + "/Features_DesignSystem.bundle"`; the documentation says to always use `Bundle.module`. - Expecting a target without resources to have `Bundle.module`, or expecting one target's accessor to find another target's files. - Putting resources in a folder outside the target's directory, where they are not part of any target.

  • The app needs the URL of a JSON file that ships in a package. How should the package expose it?
    Through public API in the target that owns the file: a `public static var` or function that calls `Bundle.module.url(forResource:withExtension:)` internally. The app cannot write `Bundle.module` for another module, and it should not guess the resource bundle's name or location on disk.
  • Why can a package target that has no resources not use `Bundle.module`, even when a sibling target in the package has resources?
    SwiftPM generates the accessor per module, only for modules with resources, and makes it internal. A sibling's accessor belongs to that sibling's module and is inaccessible outside it; the sibling should expose a public loader instead.

  • Package resources are copied into the app's main bundle, so Bundle.main finds them.
  • Bundle.module is public, so the app target can use it to reach any package's resources.
  • Image("logo") inside a package view finds the package's asset catalog automatically.
  • Every package target gets a Bundle.module, whether or not it declares resources.
  • Building the path to the package's .bundle by hand is fine because its name never changes.