# SwiftTweaks: Live iOS Tuning Without Recompilation

> SwiftTweaks lets iOS developers expose selected Swift values through an on-device controls interface and edit them without rebuilding. It is aimed at Swift projects that need rapid tuning of animation, layout, color, and feature-flag values.

**bryanjclark/SwiftTweaks** — Tweak your iOS app without recompiling! 

- Repository: https://github.com/bryanjclark/SwiftTweaks
- Stars: 1,440 · Forks: 143
- Language: Swift
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/bryanjclark-swifttweaks

## Why SwiftTweaks Replaces Rebuild-Driven iOS Tuning

SwiftTweaks addresses a specific iOS development problem: changing usability-related constants in a Swift app and waiting for Xcode to rebuild before seeing their effect. The README focuses on animation durations and delays, font sizes, colors, and layouts. Its central premise is that a value can look acceptable in a design tool or simulator but behave differently when the finished app is held on a physical device.

The library is for developers working in Swift on iOS. Instead of keeping every tuning value as a plain constant throughout the app, the developer declares selected values as `Tweak` objects. A tweak can carry a name, default value, and editable constraints or options. The app then presents those values through a `TweakWindow`, which the README says is opened by shaking the phone after the project has been built and run.

This is a development-time tuning layer, not a general configuration service. The supported types are `Bool`, `Int`, `CGFloat`, `Double`, `UIColor`, `String`, `StringOption`, and `TweakAction`. The README does not describe editing arbitrary Swift properties, rebuilding source code, changing compiled logic, or modifying an app that was not built with SwiftTweaks. Those boundaries matter because adopting the package name alone does not make an iOS app remotely configurable.

## Tweak Declarations, Stores, and Runtime Editing

The data flow begins with a type that conforms to `TweakLibraryType`. That type declares its tuning values as `public static` properties and creates a `TweakStore`. Application code reads the properties, while the store gives the tweak interface a collection of editable values and controls whether tweaks are active.

A scalar color tweak needs a category, group, label, and default value:

```swift
public static let colorTint = Tweak("General", "Colors", "Tint", UIColor.blue)
```

The static property remains the application-facing handle. A numeric tweak can specify a default and minimum. A `StringOption` can constrain the selection to named choices. This makes the declaration act as both the code reference and the description shown by the tuning interface, although the README does not explain how labels are rendered after localization.

A store collects individual tweaks and templates. In the documented example, `allTweaks` includes colors, margins, a feature flag, and a spring animation template. The store's `enabled` argument comes from `TweakDebug.isActive`. That design allows the collection to exist as part of the app while tying availability to a debug state. The README does not specify the mechanism behind `TweakDebug.isActive`, so developers should verify how that state is established in the source before designing the release boundary.

Persistence is central because the v4.1.2 release note identifies a fix for “tweaks-not-persisting issue.” The documented architecture includes a `TweakStore` “to persist them,” but the README does not provide a migration policy, reset command, or statement about compatibility across old stored values and later tweak declarations.

## Animations, Layouts, and Executable Tweak Actions

SwiftTweaks goes beyond a basic settings screen. Its template types package values that are normally changed together. `BasicAnimationTweakTemplate` controls delay and duration for `UIView.animate`. `SpringAnimationTweakTemplate` adds damping and initial spring velocity for the spring-specific API. `ShadowTweakTemplate` groups shadow color, radius, offset, and opacity for a `CALayer`. `EdgeInsetsTweakTemplate` represents top, right, bottom, and left values for `UIEdgeInsets`.

This grouping reduces the risk that a developer adjusts only half of a related visual configuration. It also makes declarations easier to scan because a common animation or shadow setup has one named entry rather than several disconnected constants. The tradeoff is tighter coupling between app code and SwiftTweaks extension APIs. A team using those templates accepts the template's particular grouping rather than defining every control independently.

`TweakAction` covers controls that trigger behavior rather than edit stored data. The developer declares an action and later registers a closure with `addClosure`. Pressing the corresponding button in the tweak window executes that closure. An identifier returned by `addClosure` can later be passed to `removeClosure`. This mechanism can invoke app-specific behavior without rebuilding, but it does not make arbitrary remote actions available. The closure must already exist in the compiled debug binary, and the README does not discuss authorization or restrictions on side effects for this action type.

## Adding a First SwiftTweaks Library to an iOS App

The README identifies SwiftPM, Carthage, and CocoaPods compatibility, and the v4.1.0 release added SwiftPM support. However, the README does not include dependency installation commands or a package target name to add to an application's dependency configuration. It also does not show the AppDelegate code needed to make `TweakWindow` the app window. Those details should be taken from the matching release source rather than inferred.

The first documented implementation step is to create a tweak library. A compact version can declare values that an app needs to inspect on a device:

```swift
public struct ExampleTweaks: TweakLibraryType {
    public static let colorTint = Tweak("General", "Colors", "Tint", UIColor.blue)
    public static let marginHorizontal = Tweak<CGFloat>(
        "General", "Layout", "H. Margins", defaultValue: 15, min: 0
    )
}
```

The app would then need a `TweakStore` containing those declarations, following the store construction shown in the README. Next, application code would reference `ExampleTweaks.colorTint` or `ExampleTweaks.marginHorizontal` in place of fixed values. Finally, the AppDelegate must make the `TweakWindow` the app window according to the project's three-step setup. Building and running the app should then make the controls reachable through the documented shake gesture.

The README ends before completing the walkthrough after `We have five tweaks in ExampleTweaks:`. It does not confirm a complete copy-and-paste setup, the exact store persistence options, or all AppDelegate requirements. A first use based only on the README would need additional source inspection.

## SwiftTweaks Compared with FBTweaks and Plain Constants

SwiftTweaks presents itself as a Swift-oriented alternative to Facebook Tweaks. The README says FBTweaks uses an `FBTweak` macro whose production use is replaced at compile time with the default value. SwiftTweaks instead exposes declared `Tweak` values through Swift APIs and a runtime editing window. That difference changes where the dependency and controls reside during development.

Compared with plain constants, SwiftTweaks adds a store, a window, supported value types, templates, persistence-related behavior, and optional actions. The benefit is direct adjustment on a device without waiting for Xcode. The cost is more code and a need to decide which constants deserve editable controls. Treating every value as a tweak could make application code and the development interface harder to navigate.

FBTweaks is also a real choice for projects that can accept Objective-C macros and compile-time replacement. SwiftTweaks is the documented fit for an app that is mostly Swift and wants editable values plus a Swift declaration model. The README does not claim that SwiftTweaks reproduces every FBTweaks feature, and it provides no capability-by-capability compatibility table. The comparison should therefore remain limited to the documented mechanisms rather than claims about speed, safety, or maintenance.

## Constraints, Release History, and Upgrade Work

The clearest limitation is scope. SwiftTweaks edits values and executes closures already compiled into a debug build. It does not remove compile-time business logic, regenerate Swift source, or document a way to change an installed production app without SwiftTweaks. It should not be selected for teams seeking a production remote-configuration platform or an automatic design-token service.

There is also a build-boundary concern. The documented `defaultStore` passes `TweakDebug.isActive` as its enabled state, but the README does not explain how that state is controlled or whether an accidental release configuration can expose the tweak window. The need to use `TweakWindow`, register a store, and keep debug controls out of the intended shipping path should be verified in the source. The README says the app window can be replaced by other options, but it does not document those options.

The repository is not archived, and its last push was on 2026-10-14. The latest listed release is v4.1.2 from 2021-01-19, whose release note records a persistence fix. Earlier releases added Dark Mode in v4.1.1 and SwiftPM support plus UI fixes in v4.1.0. This difference between repository activity and release age makes build verification important, especially for newer Swift and Xcode combinations. The repository contains `Package.swift`, `SwiftTweaks.podspec`, an Xcode project, tests, and an iOS example, but no current compatibility matrix is documented.

The project uses the MIT license. Source redistribution and modification are governed by the license text, and adopters must preserve its required notices. This is a compliance consideration rather than a guarantee of compatibility or fitness for a particular app.

## Conclusion

SwiftTweaks suits Swift developers tuning behavior on real iOS devices, especially where animation timing, spacing, colors, or feature flags need frequent adjustment. It is unsuitable for a team that cannot add an on-device controls interface or needs configuration without rebuilding a debug build. Check first whether v4.1.2 persistence, SwiftPM integration, and compatibility with the app's current Xcode and Swift toolchain meet the project's needs. The MIT license and current repository status permit adoption subject to the usual license-compliance review, but the latest published release remains v4.1.2 from 2021-01-19.

## FAQ

### Can SwiftTweaks change an iOS app without recompiling it?

Yes, for declared `Tweak` values and registered `TweakAction` closures in an app built with SwiftTweaks. The applicable logic and controls must already be present in that compiled build.

### Which value types can SwiftTweaks edit?

The documented types are `Bool`, `Int`, `CGFloat`, `Double`, `UIColor`, `String`, `StringOption`, and `TweakAction`. It also provides templates for common animation, shadow, and edge-inset settings.

### How do I open the SwiftTweaks controls in an iOS app?

After creating a tweak library, using its values, and making the `TweakWindow` the app window, the README says that building and running the app lets you shake the phone to open the Tweaks UI.

## Sources

- [bryanjclark/SwiftTweaks on GitHub](https://github.com/bryanjclark/SwiftTweaks)
- [Issues](https://github.com/bryanjclark/SwiftTweaks/issues)
- [License: MIT](https://github.com/bryanjclark/SwiftTweaks/blob/master/LICENSE)
- [README](https://github.com/bryanjclark/SwiftTweaks/blob/master/README.md)
- [Releases](https://github.com/bryanjclark/SwiftTweaks/releases)

---

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