Prefire Documentation

Prefire uses the Stencil templating language combined with Sourcery extensions for Swift code generation.

When rendering a template, the context provides three main top-level objects:

1. argument: Contains configuration values from .prefire.yml.
2. types: A collection of parsed Swift types (via Sourcery) used to identify PreviewProvider or PrefireProvider implementations.
3. argument.previewsMacrosDict: An array of models representing #Preview macro blocks found in your source code.

If you are working with a Swift package using a Package.swift manifest, add Prefire as a dependency and attach the appropriate plugins to your targets.

1. Add Dependency: Add the Prefire package to your dependencies array.
2. Attach Plugins:
   • Use PrefirePlaybookPlugin in a standard .target to generate Playbook (Demo) views.
   • Use PrefireTestsPlugin in a .testTarget to automatically generate snapshot tests when the test target is built.

dependencies: [
    .package(url: "https://github.com/BarredEwe/Prefire", from: "4.0.0")
]

// ...

.target(
    plugins: [
        // For Playbook (Demo) view
        .plugin(name: "PrefirePlaybookPlugin", package: "Prefire")
    ]
),
.testTarget(
    plugins: [
        // For Snapshot Tests
        .plugin(name: "PrefireTestsPlugin", package: "Prefire")
    ]
)

You can install the self-contained prefire CLI wrapper using Mint. The wrapper includes the PrefireBinary artifactbundle as an embedded resource.

To override the path of the embedded binary (useful for local development), set the PREFIRE_BINARY_PATH environment variable to the absolute path of your prefire executable.

mint install BarredEwe/Prefire

Prefire provides built-in Stencil templates that serve as excellent starting points for custom configurations. You can copy these templates, modify them to suit your needs, and then reference the new .stencil file in your .prefire.yml configuration.

Available built-in templates:

• Tests template: EmbeddedTemplates.previewTests (used for generating snapshot tests).
• Playbook template: EmbeddedTemplates.previewModels (used for generating preview models).

To use a custom template, ensure you specify the template_file_path in your .prefire.yml.

test_configuration:
  target: MyApp
  test_target_path: ${PROJECT_DIR}/MyAppTests
  test_file_path: MyAppTests/PreviewTests.generated.swift
  template_file_path: MyAppTests/MinimalPreviewTests.stencil
  imports:
    - UIKit

To prevent PreviewProvider and mock data from being included in your production binary, you can disable the playbook using compiler flags.

Swift Package Manager: Add the PLAYBOOK_DISABLED setting to your package configuration.

Xcode: Add PLAYBOOK_DISABLED to your SWIFT_ACTIVE_COMPILATION_CONDITIONS build settings.

// SPM
swiftSettings: [
    .define("PLAYBOOK_DISABLED", .when(configuration: .release)),
]

You can install the Prefire Command Line Interface (CLI) via Homebrew to manually trigger test or playbook generation.

Installation:

brew tap barredewe/prefire
brew install prefire

Commands:

• prefire tests: Generates snapshot tests from your previews.
• prefire playbook: Generates preview-based component models.
• Use --help with any command to view available options (e.g., prefire tests --help).

To use a custom Stencil template for generating test files, add the template_file_path key under the test_configuration section of your .prefire.yml file. You can also provide additional imports that should be included in the generated file.

test_configuration:
  target: MyApp
  test_target_path: ${PROJECT_DIR}/MyAppTests
  test_file_path: MyAppTests/PreviewTests.generated.swift
  template_file_path: MyAppTests/MinimalPreviewTests.stencil
  imports:
    - UIKit

Prefire uses Stencil templates to generate snapshot tests and Playbook models. You can override the default templates by specifying a custom .stencil file path in your .prefire.yml configuration.

Use the template_file_path key under either test_configuration or playbook_configuration.

Important: The path is resolved relative to the target directory (test_target_path for tests or target for playbook), not relative to the .prefire.yml file location.

# .prefire.yml

test_configuration:
  target: MyApp
  test_target_path: ${PROJECT_DIR}/MyAppTests
  test_file_path: MyAppTests/PreviewTests.generated.swift
  template_file_path: MyAppTests/CustomPreviewTests.stencil

playbook_configuration:
  target: ${PROJECT_DIR}/MyApp
  template_file_path: MyApp/CustomPreviewModels.stencil

Use a .prefire.yml file to configure test and playbook behavior.

Key settings:

• test_configuration.target: Specifies the app target.
• playbook_configuration.preview_default_enabled: A boolean that determines if all previews are included by default. If set to false, you must use .prefireEnabled() to include specific previews.

test_configuration:
  target: MyApp

playbook_configuration:
  preview_default_enabled: true