# Sourcery: Swift code generation from SwiftSyntax templates

> Sourcery is a Swift meta-programming tool that parses your sources with SwiftSyntax and emits boilerplate from Stencil templates. It is a good fit when you have many protocols or models that need the same generated code, and a poor fit when Apple's derived conformances already cover the case.

**krzysztofzablocki/Sourcery** — Meta-programming for Swift, stop writing boilerplate code.

- Repository: https://github.com/krzysztofzablocki/Sourcery
- Website: http://merowing.info
- Stars: 8,023 · Forks: 633
- Language: Swift
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/krzysztofzablocki-sourcery

## The boilerplate Sourcery exists to delete

The README makes the pitch with a concrete pair of examples. Without a generator, a mock for a single protocol runs to a class with a call counter, a called flag, a received argument, an invocations array and a closure, plus the method body that updates all of them. That is roughly twenty lines per protocol method. With Sourcery, the README shows the entire replacement as one line: `extension MyProtocol: AutoMockable {}`. The template behind `AutoMockable` is what produces the long class.

The intended audience is Swift developers on iOS and macOS who keep writing the same shape of code across many types. The README lists the common targets: Equality and Hashing, enum cases and counts, lenses, mocks and stubs, LinuxMain, decorators, persistence and advanced Codable, and property level diffing. The claim is broader than that list, though: if you can describe an algorithm to another human, the README says you can automate it with Sourcery. Treat that as the design goal rather than a promise, because a template you cannot express cleanly in Stencil is a template you will maintain by hand instead.

## How Sourcery parses sources and emits files

Sourcery is built on Apple's SwiftSyntax, which is the same parser Apple uses for Swift tooling. That matters for the failure modes: Sourcery reads your source files, builds a model of the declarations it finds, and hands that model to a template engine. The templates are Stencil, and the repository keeps a dedicated `SourceryStencil` target alongside `SourceryFramework`, `SourceryRuntime`, `SourceryJS`, `SourcerySwift` and `SourceryUtils`. The split is visible in the top-level layout, and it tells you the generated code can call into a runtime that ships with the tool.

The data flow is one directional. Sources in, generated Swift out. There is no round trip where Sourcery edits your handwritten files, and the README never describes one. In practice that means the generated output is a build artifact you either commit or ignore, and the annotations that trigger generation (like the empty `AutoMockable` conformance) live in your own code. If a template produces something wrong, the fix is in the template, not in the output file, because the next run overwrites it.

## Installing Sourcery and generating your first mock

The README lists five installation routes: a prebuilt binary from the release tab, Homebrew, CocoaPods, Mint, and building from source. Homebrew is the shortest path for a local run.

```bash
brew install sourcery
```

If you would rather not install globally, Mint runs the published version directly from the repository.

```bash
mint run krzysztofzablocki/Sourcery
```

CocoaPods users add the pod and run the binary from the Pods directory. The README also documents a `CLI-Only` subspec for people who want the binary without the rest.

```bash
pod 'Sourcery', :subspecs => ['CLI-Only']
```

Once the binary is on your machine, the first real use is the mocking case from the TL;DR. Mark a protocol with an empty conformance, then point Sourcery at your sources and a template. The README does not spell out a full command line in the excerpt, so check the in-depth guide linked from the README for the exact flags before you script it. What you should expect to see is a generated Swift file containing the mock class for every protocol carrying the annotation, with no handwritten mock code in your repository.

## Where Sourcery is the wrong tool

The README itself notes that Sourcery's adoption was one of the factors that pushed Apple to implement derived Equality and automatic Codable conformance. Read that as a warning about scope creep. If your only reason for adding Sourcery is to get `Equatable` or `Codable` on a handful of structs, the compiler now does that for you, and adding a template plus a build step is a net loss.

The second limitation is that generated code is still code you own. Mocks produced from a template are consistent, which the README presents as the benefit, but consistency also means a template bug is replicated across every generated file at once. The repository has a `SourceryTests` directory and a `Tests` directory, which suggests the project tests its own behaviour, but nothing in the repository documentation describes testing your templates. That gap is on you.

The third is platform and toolchain coupling. The Dockerfile pins `swift:6.0-jammy` for both builder and runtime stages and resolves dependencies with `swift package --only-use-versions-from-resolved-file resolve`. That flag means the build honours `Package.resolved` rather than picking newer versions, which is good for reproducibility and bad if you need a dependency bump that the resolved file does not contain. If your CI runs a Swift version outside what the project supports, you are on your own.

## Sourcery compared with hand-written macros and other generators

The nearest alternative is Swift's own macro system, which expands at compile time inside the compiler rather than as a separate binary producing files you can read. The difference in approach is concrete: a macro is invoked where you write it and its expansion is not a file you can open, while Sourcery writes a Swift file into your project that you can inspect, diff and commit. That inspectability is Sourcery's main advantage, and it is also why generated files show up in code review.

A second comparison the README implies is against writing the boilerplate by hand. The README's own numbers are the argument here: hundreds of lines per protocol, versus one empty conformance. Whether that trade is worth it depends on how many protocols you have. With three protocols, write the mocks. With thirty, the template pays for itself, and the README's point about refactors is the real one. Add a property to a protocol and the mock updates on the next run instead of silently going stale.

There is also a commercial sibling: Sourcery Pro, distributed on the Mac App Store, which the README describes as adding a Stencil editor and live AST templates inside Xcode. The open source tool does not include those editing features. If you want template authoring help, that is a separate purchase and a separate decision.

## Licence, maintenance and the upgrade cost

Sourcery is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive arrangement, and it is compatible with shipping the generated output inside a closed source app. This is a description of the licence text, not legal advice; read the LICENSE file in the repository if the details matter to your organisation.

Maintenance is the part to weigh. The repository is not archived, and the last push to master was on 2026-06-11. The most recent release listed is 2.3.0 from 2025-09-18, preceded by 2.2.7 in May 2025 and 2.2.6 in December 2024. So there is activity on the branch, and release cadence is measured in months rather than weeks.

Upgrade cost is mostly template drift. Because Sourcery depends on SwiftSyntax, a new Swift toolchain can change what the parser reports, and a template that relied on a particular node shape may need adjusting. The `Package.resolved` file and the Dockerfile's pinned Swift 6.0 images are the project's own answer to that problem. Pin your Sourcery version in CI the same way, and regenerate on every build so a template break shows up as a diff rather than as a surprise in a release.

## Conclusion

Adopt Sourcery when you have a repeated Swift pattern (mocks, Equatable, enum case lists, Codable) that you want generated and kept in sync with your sources. Do not adopt it for one-off code you will write once, or for cases where Swift's derived conformances already do the job. Before committing, verify three things: that your templates live in the repository and are reviewed, that the generated files are regenerated in CI so drift is caught, and that the pinned Sourcery version still builds against your toolchain, since the last push to master was on 2026-06-11 and the latest release listed is 2.3.0 from 2025-09-18.

## FAQ

### How do I install Sourcery?

The README lists a prebuilt binary from the release tab, Homebrew with `brew install sourcery`, CocoaPods, Mint with `mint run krzysztofzablocki/Sourcery`, and building from source with Swift Package Manager.

### What is Sourcery used for in a Swift project?

It generates boilerplate code from Stencil templates, with the README naming Equality and Hashing, enum cases and counts, lenses, mocks and stubs, LinuxMain, decorators, Codable support and property level diffing as the common uses.

### Does Sourcery replace writing mocks by hand?

For annotated protocols, yes. The README shows a mock that would take a class with call counters, received arguments and closures replaced by a single `extension MyProtocol: AutoMockable {}`, with the template producing the class.

### What does Sourcery use to parse Swift source?

It is built on Apple's SwiftSyntax, according to the README, and the repository separates the template engine into a SourceryStencil target alongside SourceryFramework, SourceryRuntime and SourceryUtils.

### Is Sourcery still maintained?

The repository is not archived and the last push to master was on 2026-06-11. The most recent release listed is 2.3.0 from 2025-09-18.

## Sources

- [krzysztofzablocki/Sourcery on GitHub](https://github.com/krzysztofzablocki/Sourcery)
- [License: MIT](https://github.com/krzysztofzablocki/Sourcery/blob/master/LICENSE)
- [Project website](http://merowing.info)
- [README](https://github.com/krzysztofzablocki/Sourcery/blob/master/README.md)
- [Releases](https://github.com/krzysztofzablocki/Sourcery/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/krzysztofzablocki-sourcery