Quick Start

Build your first Shaft application in minutes.

Getting Started

Since Shaft is just a regular Swift package, the easiest way to start is using the official starter template CounterTemplate:

# Clone the template
git clone https://github.com/ShaftUI/CounterTemplate.git

# Navigate to directory
cd CounterTemplate

# Run the app
swift run

That’s it! You should see a window with a counter application:

mkdir MyShaftApp
cd MyShaftApp
swift package init --type executable

// swift-tools-version: 5.10
import PackageDescription

let package = Package(
    name: "MyShaftApp",
    platforms: [.macOS(.v13)],
    dependencies: [
        .package(
            url: "https://github.com/ShaftUI/Shaft.git",
            branch: "main"
        )
    ],
    targets: [
        .executableTarget(
            name: "MyShaftApp",
            dependencies: [
                .product(name: "Shaft", package: "Shaft"), // The core Shaft framework
                .product(name: "ShaftSetup", package: "Shaft"), // Desktop backend
            ]
        )
    ]
)

import Shaft
import ShaftSetup

Shaft

runApp(
    Text("Hello, Shaft!")
)

swift run

Understanding the Code

Let’s break down the hello world example:

Imports

Import the required frameworks to access widgets and functionality:

import Observation
import Shaft
import ShaftSetup

• Observation: Swift’s built-in observation framework for reactive programming
• Shaft: The core UI framework
• ShaftSetup: Automatically configures the best backend for your platform

Backend Setup

Initialize Shaft with the default backend:

// Use the default backend
ShaftSetup.useDefault()

The Shaft core framework is platform-agnostic by design—it doesn’t depend on any specific OS or windowing system. This makes it easy to port and customize, but it means you need to provide a backend for windowing and rendering.
ShaftSetup simplifies this by automatically configuring the best backend for your platform.

Hot Reload Setup (Optional)

For faster development, enable hot reloading:

#if DEBUG && !os(Windows)
    import SwiftReload
    LocalSwiftReloader(onReload: backend.scheduleReassemble).start()
#endif

This automatically reloads your app when you make changes to the source code.

Observable State

Create reactive state using Swift’s @Observable macro:

@Observable class Counter {
    var count = 0
}

let counter = Counter()

• @Observable: Makes the class automatically notify UI when properties change
• var count: The state that will trigger UI updates when modified

Widget Definition

final class CounterView: StatelessWidget {
    func build(context: BuildContext) -> Widget {
        Column(mainAxisSize: .min, spacing: 16) {
            Text("Count: (counter.count)")
            
            Button {
                counter.count += 1
            } child: {
                Text("Increment")
            }
        }
        .center()
    }
}

• StatelessWidget: A widget that doesn’t maintain internal state
• Column: Arranges children vertically with spacing
• Button: Interactive widget with click handler
• Text: Displays content, automatically updates when counter.count changes

Running the App

runApp(
    CounterView()
)

Launches the application with your root widget.

Building a Counter App

Let’s create something more interactive:

import JavaScriptKit
import Observation
import Shaft
import ShaftWeb

// Setup ShaftWeb backend for running in ShaftPad
Shaft.backend = ShaftWebBackend { _ in
    JSObject.global.document.querySelector("canvas")
}

@Observable class Counter {
    var count = 0
}

let counter = Counter()

runApp(CounterAppView())

final class CounterAppView: StatelessWidget {
    func build(context: any BuildContext) -> any Widget {
        Column(mainAxisAlignment: .center) {
            Text("Counter Example")
                .textStyle(.init(fontSize: 24, fontWeight: .bold))

            SizedBox(height: 20)

            Text("Count: \(counter.count)")
                .textStyle(.init(color: Color(0xFF_FFA500), fontSize: 48))

            SizedBox(height: 20)

            Row(mainAxisAlignment: .center) {
                Button {
                    counter.count -= 1
                } child: {
                    Text("−")
                        .textStyle(.init(fontSize: 24))
                }
                .padding(.all(10))

                SizedBox(width: 10)

                Button {
                    counter.count += 1
                } child: {
                    Text("+")
                        .textStyle(.init(fontSize: 24))
                }
                .padding(.all(10))
            }
        }
        .center()
        .padding(.all(40))
    }
}

Next Steps

Now that you have a working Shaft application:

• Learn about Widgets - The building blocks of Shaft UI
• Explore State Management - Managing application state
• Check out more Tutorials - Real-world applications