SwiftWeb

SwiftWeb is a Swift framework for server-rendered web applications with an optional Swift WASM browser runtime. Applications describe routes and complete HTML documents in Swift, use SwiftWebUI for higher-level components, and opt individual client components into hydration, local state, and browser events.

SwiftWeb 0.8 is a developer preview. It requires the pinned Swift 6.4 development snapshot because its HTTP host uses the current lifetime-aware Swift server APIs.

flowchart LR
  App["SwiftWeb.App"] --> Scene["Scene and routes"]
  Scene --> Page["@Page"]
  Page --> Document["HTMLDocument"]
  Document --> HTML["server-rendered HTML"]
  Document --> Island["ClientComponent"]
  Island --> WASM["Swift WASM runtime"]
  WASM --> Browser["hydration, state, and events"]

SwiftWeb pins the host toolchain and WASM SDK to the same snapshot.

For WASM commands, point SwiftWeb at the real toolchain directory. A swiftly shim does not contain the matching wasm-ld executable.

export SWIFT_WEB_TOOLCHAIN_BIN="$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin"
export SWIFT_WEB_HOST_SWIFT="$SWIFT_WEB_TOOLCHAIN_BIN/swift"
export SWIFT_WEB_WASM_SWIFT="$SWIFT_WEB_TOOLCHAIN_BIN/swift"
export SWIFT_WEB_WASM_TOOLCHAIN_BIN="$SWIFT_WEB_TOOLCHAIN_BIN"

"$SWIFT_WEB_HOST_SWIFT" --version
test -x "$SWIFT_WEB_WASM_TOOLCHAIN_BIN/wasm-ld"

See Toolchain for the complete host and WASM setup.

Install the sweb executable from the 0.8.0 release with Mint:

export PATH="$SWIFT_WEB_TOOLCHAIN_BIN:$PATH"
mint install 1amageek/swift-web@0.8.0 sweb
sweb --help

Create and run an application:

sweb new MyApp --output .
cd MyApp
sweb dev

Open http://127.0.0.1:3000. If port 3000 is occupied, sweb dev selects the next available port and prints it.

The generated package depends on released versions of SwiftWeb and SwiftHTML:

// swift-tools-version: 6.4

import PackageDescription

let package = Package(
    name: "MyApp",
    platforms: [.macOS("26.2")],
    products: [
        .library(name: "MyApp", targets: ["MyApp"]),
    ],
    dependencies: [
        .package(url: "https://github.com/1amageek/swift-web.git", from: "0.8.0"),
        .package(url: "https://github.com/1amageek/swift-html.git", from: "0.14.0"),
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                .product(name: "SwiftHTML", package: "swift-html"),
                .product(name: "SwiftWeb", package: "swift-web"),
            ],
            swiftSettings: [
                .enableUpcomingFeature("ApproachableConcurrency"),
            ]
        ),
    ],
    swiftLanguageModes: [.v6]
)

An application declares its route topology through App.body:

import SwiftWeb

public struct MyApp: SwiftWeb.App {
    public init() {}

    public var body: some Scene {
        HomePage()
        AboutPage()
    }
}

A static page returns a complete HTMLDocument:

import SwiftHTML
import SwiftWeb

@Page("/")
struct HomePage {
    var document: some HTMLDocument {
        PageDocument(
            title: "Home",
            description: "A SwiftWeb application."
        ) {
            main {
                h1 { "Hello SwiftWeb" }
                p { "Rendered on the server with SwiftHTML." }
            }
        }
    }
}

Use load() and document(_:) when rendering needs asynchronous data:

import SwiftHTML
import SwiftWeb

@Page("/profile")
struct ProfilePage {
    struct Model: Sendable {
        let displayName: String
    }

    func load() async throws -> Model {
        Model(displayName: "Taylor")
    }

    func document(_ model: Model) -> some HTMLDocument {
        PageDocument(title: model.displayName) {
            main {
                h1 { model.displayName }
            }
        }
    }
}

Component is the reusable, nestable authoring unit. HTMLDocument owns a complete page and cannot be nested inside a component. The full contract is in HTML Authoring Model.

Add the SwiftWebUI product when you want higher-level layout and controls:

.product(name: "SwiftWebUI", package: "swift-web")

SwiftWebUI components lower into the same SwiftHTML graph, so raw HTML elements and SwiftWebUI values can be composed at one page boundary.

import Foundation
import SwiftHTML
import SwiftWeb
import SwiftWebUI

@Page("/")
struct HomePage {
    var document: some HTMLDocument {
        PageDocument(title: "Home") {
            main {
                VStack(spacing: .large) {
                    Text("Hello SwiftWeb").as(.h1)
                    Link("About", destination: URL(string: "/about")!)
                }
                .frame(maxWidth: 720)
            }
        }
    }
}

ClientComponent runs in the generated standard Swift WASM runtime. Its @State values and event handlers remain in the browser:

import SwiftHTML
import SwiftWebUI

public struct Counter: ClientComponent {
    @State private var count = 0

    public init() {}

    public var content: some Component {
        VStack(spacing: .small) {
            Text("Count: \(count)")
            Button("Increment") {
                count += 1
            }
        }
    }
}

The default contract places small client components in the eager main bundle. Large or deferred islands can declare a loading and bundle policy:

public static let loadPolicy: LoadPolicy = .visible
public static let bundle: BundlePolicy = .named("analytics")

Available load policies are .eager, .visible, .interaction, .idle, and .manual. See Client Bundle Loading for bundle resolution, ownership, and production behavior.

sweb dev maintains desired source state and the currently serving worker. It materializes generated packages, rebuilds changed browser/server paths, swaps a ready worker, and recovers from build failures without discarding the last good application.

flowchart LR
  Edit["edit Sources"] --> Dev["sweb dev"]
  Dev --> Prepare["materialize .swiftweb/generated"]
  Prepare --> Build["build WASM and server worker"]
  Build --> Serve["serve latest successful generation"]
  Serve --> HMR["browser HMR or page patch"]
  HMR --> Edit

Generated content is build output. Keep application changes in Package.swift and Sources; do not edit .swiftweb/generated directly.

All package commands accept --package-path <directory>. Build, dev, and Storyboard commands also accept --scratch-path <directory>.

Run sweb xcode to use the generated <AppName>-dev scheme in Xcode:

cd MyApp
sweb xcode

Build the generated server package:

cd MyApp
sweb build

Build the standard browser WASM runtime with the matching SDK:

sweb build \
  --wasm \
  --runtime standard \
  --swift-sdk swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm \
  -c release

The production artifact processor strips non-runtime sections, runs wasm-opt -Oz when available, records a size report, and writes cached gzip and Brotli sidecars:

.swiftweb/generated/.build/wasm/out/Products/Release-webassembly-wasm32/
  <product>.wasm
  <product>.wasm.size.json
  <product>.wasm.compression.json
  <product>.wasm.gz
  <product>.wasm.br

The public browser profile is standard Swift WASM. Embedded Swift WASM is not a supported SwiftWeb browser runtime.

MyApp/
├─ Package.swift
├─ Sources/MyApp/
│  ├─ App.swift
│  ├─ Routes/
│  └─ Components/
└─ .swiftweb/                 generated; do not edit
   ├─ generated/dev/
   ├─ generated/server/
   └─ generated/wasm/

SwiftWeb itself is split into runtime, browser, UI, development, and host targets. The documentation index maps each current contract to its owning area.

Deployment integrations live outside the core package. sweb new can apply a preset or GitHub-backed adapter template and records its source in .swiftweb/platform.json:

sweb new Chat --ai --platform cloudflare --output .
sweb new App --platform owner/repository --output .
sweb new App --platform owner/repository/template --output .

The adapter repository contract is documented in Platform Adapter Template Contract.

cd Examples/HelloWorld
sweb dev

Read the changelog for release-level changes, then use the documentation index for current public contracts, architecture decisions, and verification runbooks.

Use the pinned toolchain for every validation command. Native tests run through Xcode with a timeout guard:

TOOLCHAINS=org.swift.64202607171a \
scripts/swift-test-hang-guard.sh \
  --repeats 1 \
  --timeout 1200 \
  --build-timeout 1200 \
  -- xcodebuild test \
    -scheme swift-web-Package \
    -destination platform=macOS \
    -jobs 2 \
    -parallel-testing-enabled NO

The complete browser-visible development path is verified separately:

cd Tests/BrowserE2E
npm run counter-wasm

See Development Reconciler Verification for the required environment and acceptance conditions.

SwiftWeb is available under the MIT License.