skip to content

As the lead of a Swift codebase, how do you decide whether to adopt a third-party macro package, write your own macros, or avoid macros for a given problem?

level: principalimportance: should knowfreq 15%

answer

  1. a build-time program, not just syntax
  2. simpler language features first
  3. one swift-syntax version per graph
  4. trust: someone else's code in your build
  5. expansion tests and readable output

basics

~20 s

Treat a macro as a build-time dependency: weigh clean-build cost, swift-syntax version coupling, trust in a plug-in that runs during builds and writes into your binary, and whether the expansion is readable and tested. Prefer plain language features when they suffice.

solid answer

~50 s

I start from the problem: if generics, a protocol extension, a property wrapper or a result builder removes the boilerplate, that wins, because none of them needs a plug-in. A macro earns its place when it must generate declarations from a type's shape or turn a bad literal into a build error. Then the costs. Every macro package depends on swift-syntax, whose version tracks the Swift release, and SwiftPM settles on one version for the whole graph, so packages with non-overlapping ranges cannot coexist. Clean and CI builds pay for swift-syntax unless a prebuilt is used. The plug-in is someone else's code running in your build and writing into your binary, which is why Xcode asks you to trust macros and `xcodebuild -skipMacroValidation` carries a security warning. Whatever we adopt or write must be small, maintained and covered by expansion tests.

go deeper

for a junior

Recall that a macro package brings a plug-in into the build and that Xcode asks you to trust it before running it.

for a middle

Explain why every macro package depends on swift-syntax and what that means for builds and dependency resolution.

for a senior

Show how you would vet a macro package: read its expansions, check its tests and swift-syntax range, and measure clean-build cost.

for a principal

Own the policy: when plain language features are enough, when a macro is worth its build cost and trust, and who maintains in-house macros across toolchains.

## The decision A Swift macro is two things at once: a language feature that removes boilerplate or moves a check to compile time, and a **build-time program** that runs on every developer machine and CI runner. A lead deciding whether to adopt a third-party macro package, write in-house macros, or avoid macros for a problem is deciding about the second as much as the first. Start from the problem, not the tool. Swift already has features that remove repetition **without a plug-in**: 1. **Generics and protocol extensions** for behaviour shared across types. 2. **Property wrappers** for repeated storage logic on properties. 3. **Result builders** for declarative construction of values. 4. **Synthesized conformances** (`Equatable`, `Hashable`, `Codable`) for the common cases they cover. A macro earns its place when none of these can express the code, typically because it must generate **declarations** (members, overloads, conformances) from a type's shape, or because it should turn a mistake in a **literal** into a build error. ## What a macro costs | Cost | Where it shows | Mitigation | |---|---|---| | Build time | clean and CI builds must build or fetch swift-syntax and the plug-in | prebuilt swift-syntax where the toolchain supports it; CI caching | | Version coupling | every macro package depends on swift-syntax, and resolution settles on one version for the whole graph | few macro dependencies; packages with wide, current ranges | | Trust | the plug-in is someone else's code running during your build and writing into your binary | review, pin versions, prefer small and maintained packages | | Debuggability | errors can point into generated code | expansion tests, Expand Macro, readable output | | Tooling | each expansion is more code to type-check and index | keep expansions small; avoid `arbitrary` names | The swift-syntax coupling deserves emphasis. SE-0394 says macros are expected to depend on swift-syntax with a version tied to a major Swift release, and that SwiftPM resolution is **workspace-wide**, so all macros consolidate on one swift-syntax version. Two packages whose ranges do not overlap cannot be resolved together, even if neither uses the other. ## Trust - The book says a macro implementation runs in a **sandbox** without file-system or network access. That limits what the plug-in can reach while it runs; it says nothing about whether the code it **emits** into your app is correct or benign. - Xcode asks you to trust and enable a package's macros before it runs them. On CI, `xcodebuild -skipMacroValidation` skips that validation, and its own help text warns that this "can be a security risk if they are not from trusted sources". - Pin macro packages to exact versions or reviewed ranges, and read the expansion of every macro used in security-sensitive code. ## Debuggability Macros are more transparent than they look, because the output is ordinary Swift: - Expand Macro in Xcode and `-Xfrontend -dump-macro-expansions` show what was generated; - errors in generated code are reported inside a buffer named after the macro; - `assertMacroExpansion` tests pin the expansion, so a change in a dependency shows up as a failing test rather than a behaviour change. The risk is less "cannot debug" than "nobody looked": an attached macro that adds a conformance or replaces a body changes behaviour without any visible change in the source under review. ## A team policy 1. **Prefer language features** that need no plug-in; a macro proposal says why they are not enough. 2. **Adopt third-party macros sparingly**: small, maintained, tested, with a swift-syntax range that tracks current releases. 3. **Write in-house macros** only with expansion tests in the same change and a named owner who keeps them building on each new toolchain. 4. **Keep roles narrow**: peers and members that add code beat body macros that rewrite it. 5. **Measure** clean-build and CI time before and after adoption, and keep the plug-in builds cached. This is a judgment call with no single answer. A large app with hundreds of models may gain more from a member-and-extension macro than it pays in build time; a small library may be better served by a protocol extension and no plug-in at all.

  • Two macro packages in the app suddenly stop resolving after one updates. What happened?
    Both depend on swift-syntax, and SwiftPM resolves a single swift-syntax version for the whole dependency graph. If the updated package now requires a range that no longer overlaps the other's, resolution fails even though the two packages never import each other. The fix is a compatible release of the lagging package, or dropping one.
  • Does the plug-in sandbox make third-party macros safe to adopt without review?
    No. The sandbox keeps the implementation from reaching the file system or network while it expands a macro. The code it generates is compiled into your app with your app's permissions, so a buggy or hostile expansion is still your problem. Review the expansions of anything security-sensitive and pin the version.
  • When is writing an in-house macro clearly worth it?
    When the same declarations are hand-written across dozens of types and drift, such as mocks, overloads or conformances derived from stored properties, and no generic or protocol extension can produce declarations. Even then, ship it with expansion tests and an owner who updates it for each toolchain.

  • The sandbox means a third-party macro's generated code is safe to ship unreviewed.
  • Each macro package can use its own swift-syntax version independently.
  • Macros are free at build time because they run only once per project.
  • A macro is the first tool to reach for to remove any repetition.
  • Generated code cannot be inspected, so macro bugs are undebuggable.

Assumes the Swift 6.4 toolchain, whose swift build lists --enable-experimental-prebuilts as the default so macros can use prebuilt swift-syntax libraries.