In a Swift package target that bundles resources, how does its code load them through Bundle.module, and why does Bundle.main miss them?
answer
- a bundle per module
- generated, not written by you
- internal to the target
- the main bundle is the app's
- bundle: .module
basics
~20 sSwiftPM 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 sFrom 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 linesimport 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
Remember that package resources live in their own bundle and that package code reaches them with Bundle.module, not Bundle.main.
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.
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.
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.