Sourcery for Swift: Complete Guide to Code Generation

\n\n

1. What is it and why is it needed?

\n

Sourcery is a powerful code generation tool for the Swift language, created by Krzysztof Zabłocki and his team. It allows you to automatically generate boilerplate code based on annotations and the structure of your source files. Instead of manually writing repetitive protocol implementations, Equatable, Hashable, Codable, mock objects for testing, or code for working with Auto Layout, you describe the generation rules once, and Sourcery does the rest.

\n\n

Why is this needed? In real-world Swift projects, a significant portion of the code is mechanical and repetitive. This not only wastes developer time but is also a source of errors: forgot to add a new field to Equatable — you get a bug. Sourcery solves this problem by handling the routine. It analyzes your code (AST — Abstract Syntax Tree) and, based on templates (Stencil or Swift-based), generates new files. This is especially useful in large projects with dozens or hundreds of models, ViewControllers, or services.

\n\n

Sourcery is not a runtime library — it is a compile-time tool. You run it as part of the build process (via a Build Phase in Xcode or through SPM/Tuist), it generates files, and then those files are compiled together with the rest of the code. This approach guarantees zero runtime overhead and complete predictability.

\n\n

2. Installation

\n

There are several ways to install Sourcery. The simplest and recommended method is via Homebrew:

\n

brew install sourcery

\n\n

For projects using Swift Package Manager (SPM), you can add Sourcery as a plugin. However, it is most often used as a separate binary called from a build script. For installation via Mint (a package manager for Swift tools):

\n

mint install krzysztofzablocki/Sourcery

\n\n

You can also download a pre-built binary from GitHub Releases and place it in your project folder. After installation, make sure the command is available:

\n

sourcery --version

\n\n

3. Quick Start — Minimal Working Example

\n

Let's create a simple example: automatic generation of the Equatable protocol implementation for a struct.

\n\n

Step 1: Create a source code file (e.g., Sources/Models/User.swift):

\n

import Foundation\n\n// sourcery: AutoEquatable\nstruct User {\n    let id: Int\n    let name: String\n    let email: String\n}

\n\n

Note the comment // sourcery: AutoEquatable — this is an annotation that tells Sourcery to generate an Equatable implementation for this struct.

\n\n

Step 2: Create a template (e.g., Templates/AutoEquatable.stencil):

\n

// Generated by Sourcery\n// swiftlint:disable all\n\n{% for type in types.all where type.annotations.AutoEquatable %}\nextension {{ type.name }}: Equatable {\n    static func == (lhs: {{ type.name }}, rhs: {{ type.name }}) -> Bool {\n        {% for variable in type.storedVariables %}\n        {% if not forloop.first %} && {% endif %}lhs.{{ variable.name }} == rhs.{{ variable.name }}\n        {% endfor %}\n    }\n}\n{% endfor %}

\n\n

Step 3: Run Sourcery:

\n

sourcery --sources Sources/Models --templates Templates --output Generated

\n\n

Step 4: Result — a file AutoEquatable.generated.swift will appear in the Generated folder:

\n

// Generated by Sourcery\