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.14.0 is a developer preview requiring the pinned Swift 6.4 development snapshot. This README describes the released Service Actor routing and adapter contracts. See 0.14.0.

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-08-14-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.14.0 release with Mint:

export PATH="$SWIFT_WEB_TOOLCHAIN_BIN:$PATH"
mint install 1amageek/swift-web@0.14.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.14.0"),
        .package(url: "https://github.com/1amageek/swift-html.git", from: "0.16.1"),
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                .product(name: "SwiftHTML", package: "swift-html"),
                .product(name: "SwiftWeb", package: "swift-web"),
            ],
            swiftSettings: [
                .enableUpcomingFeature("ApproachableConcurrency"),
            ]
        ),
    ],
    swiftLanguageModes: [.v6]
)

To try changes from a checkout, build the CLI and run the example from that same checkout instead of mixing a released CLI with source from main:

git clone https://github.com/1amageek/swift-web.git
cd swift-web
"$SWIFT_WEB_HOST_SWIFT" build --product sweb --jobs 2
export PATH="$PWD/.build/debug:$PATH"
cd Examples/CounterApp
sweb dev

The bundled examples resolve SwiftWeb from the repository root. See CounterApp for its local hosting model.

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()
    }
}

App owns only the declarative application definition. The host owns its server configuration and lifecycle, then renders the app through SwiftWeb's common rendering boundary:

import SwiftWebHTTPServerHost

let host = HTTPServerHost(hostname: "127.0.0.1", port: 8080)
try await host.run(MyApp())

App.run() is the command-line convenience over this same path. Host adapter authors should follow the Host Rendering Contract.

SwiftWeb uses Swift Distributed Actors for identity-scoped remote state. The concrete actor declaration remains the interface whether the actor is local or hosted by another Service application.

import Distributed
import SwiftWeb

distributed actor CounterService {
    typealias ActorSystem = WebActorSystem

    private var value = 0

    distributed func increment() async throws -> Int {
        value += 1
        return value
    }
}

Bind an externally hosted actor at the page or scene that consumes it:

CounterPage()
    .actor(CounterService.self, identity: "primary")

Inside a bound page, Server Action, or client component, resolve and call the same concrete type:

@RemoteActor private var counter: CounterService

func increment() async throws -> Int {
    try await counter.increment()
}

ActorGroup registers construction and hosting policy in the application that owns the actor; .actor(Type.self, identity:) selects a reference in the caller. Swift code owns the type and logical identity. sweb.json selects the Service build/deploy unit, and the deployment adapter supplies transport and endpoint templates. URLs, credentials, adapter names, and artifact names do not enter the actor call site. Destinations without Actor ownership and isolation remain Server connections.

When the deployment supplies only a hostRoute, browser calls go through the primary application's same-origin Actor endpoint and authorization before the Service hop. An explicit clientRoute selects direct browser routing. See browser Service routing for the binding, authorization, and ownership requirements.

See the Actor runtime contract and the adapter contract.

The native host can terminate TLS directly through swift-tls-nio. Supply a server-side TLSConfiguration through the host-owned transport configuration:

import SwiftWebHTTPServerHost
import TLS

let identity = TLSIdentity(
    privateKey: privateKeyBytes,
    keyType: .ecdsaP256,
    certificateChain: [Certificate(der: leafCertificateDER)]
)
let transport = try HTTPServerTransportConfiguration.tls(
    .server(identity: identity, alpn: ["http/1.1"])
)
let host = HTTPServerHost(
    hostname: "0.0.0.0",
    port: 8443,
    transport: transport
)

try await host.run(MyApp())

The same listener serves HTTPS routes and WSS upgrades. TLS is installed before the HTTP/1.1 and WebSocket handlers, so route and WebSocket APIs continue to receive plaintext while transport bytes remain encrypted. An empty ALPN list is normalized to http/1.1; unsupported protocols fail during transport configuration instead of selecting a codec the host cannot serve.

Browser clients should derive WebSocket URLs from the page origin. An HTTPS page therefore resolves its socket endpoint to wss://; HTTP continues to use ws:// for explicitly plaintext development listeners.

Binary callbacks receive WebSocketBinaryBuffer, an immutable owner plus a readable range. Slicing and forwarding that value retain adapter-native storage without materializing [UInt8]; withUnsafeBytes provides a scoped borrow and copyBytes() is the explicit conversion for APIs that require an array.

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>. Lifecycle commands select their default environment from the source-controlled sweb.json.

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

cd MyApp
sweb xcode

Build the complete selected environment. Service adapters build independent service applications, the Host adapter owns primary application compilation, and the Deployment adapter owns platform validation:

cd MyApp
sweb build --environment production

Deploy only after the same environment has passed prepare and build:

sweb deploy --environment production

sweb deploy reruns prepare and build before the deployment operation. Remote state changes remain isolated to selected Service and Deployment adapter deploy tasks.

The browser runtime profile is selected at the build boundary. Application source keeps the same actor call surface in both profiles:

sweb build --environment production --runtime embedded

Embedded builds use the pinned matching Embedded WASM SDK. The development server remains a Standard WASM workflow; use prepare, build, or deploy for Embedded artifacts.

MyApp/
├─ Package.swift
├─ sweb.json                  source-controlled environments
├─ Sources/MyApp/
│  ├─ App.swift
│  ├─ Routes/
│  └─ Components/
└─ .swiftweb/                 generated; do not edit
   └─ generated/
      ├─ environments/<name>/workspace/
      │  └─ services/<service-name>/
      ├─ dev/
      ├─ server/
      └─ 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 adds the selected adapter as a SwiftPM dependency and writes its environment selection to sweb.json:

sweb new Chat --ai --adapter owner/repository --output .
sweb new App --adapter owner/repository --output .

The adapter repository contract is documented in Host, Deployment, and Service Adapter Contract. Service applications remain build/deploy units rather than Swift-facing interfaces. Actor connections retain the concrete Swift Distributed Actor surface described by the Actor runtime 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. Run the non-Metal Native tests with SwiftPM. Bound compilation separately so a cold build does not consume the test execution budget:

scripts/swift-test-timeout.sh 1200 -- "$SWIFT_WEB_HOST_SWIFT" build --build-tests --jobs 2
scripts/swift-test-timeout.sh 120 -- "$SWIFT_WEB_HOST_SWIFT" test --skip-build

Use --filter <SuiteOrTestName> for focused runs. Browser tests are opt-in; the Service Actor HTTP boundary gate checks forwarding between two native hosts through Chromium. It is separate from the Swift-WASM hydration and development-loop gate, which requires the full Chromium suite plus WebKit hydration, navigation-free Actor mutation, and reload persistence. WebKit launch is checked before Swift builds; both counter npm commands select this same required gate:

cd Tests/BrowserE2E
npm run install-webkit
npm run counter-wasm

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

SwiftWeb is available under the MIT License.