{"id":51891946,"url":"https://github.com/1amageek/swift-web","last_synced_at":"2026-07-26T05:01:33.468Z","repository":{"id":365902277,"uuid":"1274274755","full_name":"1amageek/swift-web","owner":"1amageek","description":"Swift server and browser runtime for HTML-first web apps","archived":false,"fork":false,"pushed_at":"2026-07-23T12:19:56.000Z","size":2506,"stargazers_count":23,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-23T14:08:29.989Z","etag":null,"topics":["cli","developer-tools","hmr","hot-reload","html","server-side-swift","swift","swiftpm","swiftui","vapor","wasm","webassembly"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1amageek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-19T10:52:27.000Z","updated_at":"2026-07-23T12:20:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1amageek/swift-web","commit_stats":null,"previous_names":["1amageek/swift-web"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/1amageek/swift-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1amageek%2Fswift-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1amageek%2Fswift-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1amageek%2Fswift-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1amageek%2Fswift-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1amageek","download_url":"https://codeload.github.com/1amageek/swift-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1amageek%2Fswift-web/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35901460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-26T02:00:06.503Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","hmr","hot-reload","html","server-side-swift","swift","swiftpm","swiftui","vapor","wasm","webassembly"],"created_at":"2026-07-26T05:01:32.754Z","updated_at":"2026-07-26T05:01:33.452Z","avatar_url":"https://github.com/1amageek.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwiftWeb\n\nSwiftWeb is a Swift server and browser runtime for building HTML-first web apps with\ntyped routing, server actions, SwiftWebUI components, and WebAssembly-powered client\nislands.\n\n\u003e Status: developer preview. Host, browser/WASM, and Embedded WASM development\n\u003e use the pinned Swift 6.4 development snapshot documented below.\n\n```mermaid\nflowchart LR\n  A[\"SwiftWeb.App\"] --\u003e B[\"Scene graph\"]\n  B --\u003e C[\"Page / PageGroup\"]\n  B --\u003e D[\"Route policies\"]\n  C --\u003e E[\"SwiftHTML render graph\"]\n  E --\u003e F[\"HTML response\"]\n  E --\u003e G[\"Client WASM island\"]\n  G --\u003e H[\"SwiftWebUIRuntime\"]\n  G --\u003e L[\"@RemoteActor resolved services\"]\n  L --\u003e M[\"@Resolvable distributed actor\"]\n  I[\"Server actions\"] --\u003e J[\"request context\"]\n  J --\u003e K[\"@Session\"]\n```\n\n## Packages\n\nSwiftWeb keeps product names stable while grouping source directories by\nresponsibility. `Sources/` direct children are ownership boundaries; nested\ndirectories describe the responsibility implemented by each SwiftPM target.\n\n```text\nSources/\n  SwiftWeb/\n  SwiftWebRuntime/{Core,Actors}/\n  SwiftWebBrowser/{Runtime,ClientRuntime}/\n  SwiftWebHost/\n  SwiftWebHTTPServer/Host/\n  SwiftWebUI/{Components,Style,Theme}/\n  SwiftWebDevelopment/{Facade,Hooks,DevServer,PackageGeneration,WasmBuild,StoryboardTooling,Storyboard}/\n  SwiftWebCLI/\n  SwiftWebMacros/\n```\n\n| Product | Source directory | Responsibility |\n|---|---|---|\n| `SwiftWeb` | `Sources/SwiftWeb/` | Public app facade and source macro entrypoints. |\n| `SwiftWebCore` | `Sources/SwiftWebRuntime/Core/` | Route, action, page, session, security, streaming, and server-rendering contracts used by host adapters. |\n| `SwiftWebActors` | `Sources/SwiftWebRuntime/Actors/` | Transport-neutral distributed actor invocation support. |\n| `SwiftWebBrowserRuntime` | `Sources/SwiftWebBrowser/Runtime/` | Browser runtime descriptors, WASM asset routes, host scripts, and HTML runtime injection. |\n| `SwiftWebUIRuntime` | `Sources/SwiftWebBrowser/ClientRuntime/` | Browser-side WASM bridge and JavaScriptKit runtime adapter for client components. |\n| `SwiftWebHost` | `Sources/SwiftWebHost/` | Host-neutral lowering contracts (route tables, request/response bridging) that platform adapters implement. |\n| `SwiftWebHTTPServerHost` | `Sources/SwiftWebHTTPServer/Host/` | Default HTTP server host on `swift-http-server` for local development workers, Cloud Run, and native/container server builds. |\n| `SwiftWebUI` | `Sources/SwiftWebUI/Components/` | SwiftUI-inspired component layer built on top of SwiftHTML. |\n| `SwiftWebStyle` | `Sources/SwiftWebUI/Style/` | Atomic style classes, typed selectors, and CSS-safe declaration registration. |\n| `SwiftWebUITheme` | `Sources/SwiftWebUI/Theme/` | Host-neutral theme tokens, the `Theme` model, root stylesheet, colors, materials, and spacing values. |\n| `SwiftWebDevelopmentHooks` | `Sources/SwiftWebDevelopment/Hooks/` | Worker-side development hooks and typed HMR contracts. |\n| `SwiftWebWasmBuild` | `Sources/SwiftWebDevelopment/WasmBuild/` | Toolchain resolution, WASM artifact processing, compression, and build profiles. |\n| `SwiftWebPackageGeneration` | `Sources/SwiftWebDevelopment/PackageGeneration/` | Generated server/dev/WASM package materialization and manifest inspection. |\n| `SwiftWebDevServer` | `Sources/SwiftWebDevelopment/DevServer/` | Persistent dev host, watcher, HMR event stream, worker supervision, and rebuild orchestration. |\n| `SwiftWebStoryboardTooling` | `Sources/SwiftWebDevelopment/StoryboardTooling/` | Managed Storyboard package scaffold/materialization and dev runtime launch. |\n| `SwiftWebStoryboard` | `Sources/SwiftWebDevelopment/Storyboard/` | Storyboard catalog components and routes. |\n| `SwiftWebDevelopment` | `Sources/SwiftWebDevelopment/Facade/` | Convenience facade that re-exports development modules. |\n| `sweb` | `Sources/SwiftWebCLI/` | CLI for new projects, dev server, Storyboard, and production builds. |\n\n## Architecture\n\nThe runtime core is host-neutral: `SwiftWebHost` defines the lowering\ncontracts, and platform adapters serve the same `App`/`Scene`/`Page` model on\ndifferent hosts. The built-in default host is `SwiftWebHTTPServerHost` on\n[`swift-http-server`](https://github.com/swift-server/swift-http-server).\nPlatform-specific adapters live in sibling packages:\n\n- [`swift-web-cloudflare`](https://github.com/1amageek/swift-web-cloudflare) —\n  Cloudflare Workers + per-identity Durable Object actor hosting (WebSocket\n  actor transport included), with a `swiftweb-cloudflare` installer CLI for the\n  deploy layout.\n- [`swift-web-vapor`](https://github.com/1amageek/swift-web-vapor) — Vapor\n  host adapter. Consumable via `branch:`/`revision:` only until Vapor 5 ships a\n  release with stable dependencies.\n\nDistributed actors are declared per identity with the `ActorGroup` scene, are\nreachable over HTTP (`/_swiftweb/actors/invoke`) and WebSocket\n(`/_swiftweb/actors/ws`), and scene-level `.environment()` values flow to\npages, actions, streams, actors, and client-visible keys into WASM hydration.\n\nSee [Platform Host Architecture](docs/PlatformHostArchitecture.md) for the\nresponsibility split and [Cloudflare Actor Roadmap](docs/CloudflareActorRoadmap.md)\nfor the distributed-actor program.\nSee [Directory And File Structure Design](docs/DirectoryFileStructureDesign.md)\nfor the source layout and file placement rules. See [Actor Injection Design](docs/ActorInjectionDesign.md)\nfor the `@RemoteActor` client component API over Apple's `@Resolvable` distributed\nactor model.\n\n## Requirements\n\n| Area | Requirement |\n|---|---|\n| Swift tools version | `6.4` |\n| Swiftly selector | `6.4-snapshot-2026-07-17` |\n| Swift toolchain | `swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a` |\n| Browser WASM SDK | `swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm` |\n| Embedded WASM SDK | `swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm-embedded` |\n| Platforms | macOS package development; browser runtime via WASM |\n\nSwiftWeb pins the host compiler and both WASM SDK profiles to one snapshot:\n\n```mermaid\nflowchart LR\n  A[\"Swift 6.4 snapshot\"] --\u003e B[\"Host/dev server graph\"]\n  A --\u003e C[\"Browser WASM SDK\"]\n  A --\u003e D[\"Embedded WASM SDK\"]\n  E[\"Generated packages\"] --\u003e B\n  E --\u003e C\n```\n\nUse the real snapshot toolchain executable for WASM builds, not a `swiftly` shim:\n\n```bash\nexport SWIFT_WEB_TOOLCHAIN_BIN=\"$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin\"\nexport SWIFT_WEB_HOST_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_TOOLCHAIN_BIN=\"$SWIFT_WEB_TOOLCHAIN_BIN\"\n```\n\nVerify the complete toolchain contract before the first build:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" --version\ntest -x \"$SWIFT_WEB_WASM_TOOLCHAIN_BIN/wasm-ld\"\n\"$SWIFT_WEB_WASM_SWIFT\" sdk list | \\\n  rg 'swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm(-embedded)?'\n```\n\nThe exact snapshot, both SDK identifiers, update checklist, and SwiftPM 6.4\nartifact layout are recorded in\n[Swift 6.4 Toolchain Migration](docs/Swift64ToolchainMigration.md).\n\n### Why Swift 6.4\n\nSwiftWeb's host HTTP stack builds on the next-generation server packages\n[`swift-http-server`](https://github.com/swift-server/swift-http-server)\n(`NIOHTTPServer`) and\n[`swift-http-api-proposal`](https://github.com/apple/swift-http-api-proposal)\n(`HTTPAPIs`). Both declare `// swift-tools-version:6.4` and enable the\n`LifetimeDependence` upcoming feature (the `Span` / lifetime-dependency model\nused for zero-copy HTTP I/O), so they can only be resolved and built with a\nSwift 6.4 toolchain. SwiftPM refuses to resolve a graph whose dependency\nmanifest declares a newer tools version than the selected toolchain. The\nprevious Swift 6.3.1 baseline therefore cannot resolve the current host graph.\n\nSwiftWeb ships as a developer preview because the host stack rides Apple's\nstill-evolving 6.4-era server APIs (`swift-http-server` 0.x). The repository\ntherefore pins the exact toolchain and matching WASM SDK snapshot instead of\nsilently selecting another 6.4 build.\n\n## Installation\n\nThe current developer-preview release is `0.6.4`. Depend on it by version:\n\n```swift\n// swift-tools-version: 6.4\nimport PackageDescription\n\nlet package = Package(\n    name: \"MyApp\",\n    platforms: [\n        .macOS(\"26.2\"),\n    ],\n    products: [\n        .library(name: \"MyApp\", targets: [\"MyApp\"]),\n    ],\n    dependencies: [\n        .package(url: \"https://github.com/1amageek/swift-web.git\", from: \"0.6.4\"),\n        .package(url: \"https://github.com/1amageek/swift-html.git\", from: \"0.11.0\"),\n    ],\n    targets: [\n        .target(\n            name: \"MyApp\",\n            dependencies: [\n                .product(name: \"SwiftHTML\", package: \"swift-html\"),\n                .product(name: \"SwiftWeb\", package: \"swift-web\"),\n                .product(name: \"SwiftWebUI\", package: \"swift-web\"),\n            ],\n            swiftSettings: [\n                .enableUpcomingFeature(\"ApproachableConcurrency\"),\n            ]\n        ),\n    ],\n    swiftLanguageModes: [.v6]\n)\n```\n\n\u003e **Toolchain:** resolving and building SwiftWeb requires the pinned **Swift\n\u003e 6.4** snapshot (see [Why Swift 6.4](#why-swift-64)). Point SwiftPM at its\n\u003e real executable:\n\u003e\n\u003e ```bash\n\u003e SWIFT_BIN=\"$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin/swift\"\n\u003e \"$SWIFT_BIN\" build\n\u003e ```\n\n### Install The CLI With Mint\n\nMint can install the `sweb` executable product directly from the repository. Pin\n`@0.6.4` for a reproducible install; `@main` tracks the latest development.\n\nMint invokes `swift` from `PATH`, so put the pinned Swift 6.4 snapshot first for\nthe current shell:\n\n```bash\nexport SWIFT_WEB_TOOLCHAIN_BIN=\"$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin\"\nexport PATH=\"$SWIFT_WEB_TOOLCHAIN_BIN:$PATH\"\nmint install 1amageek/swift-web@0.6.4 sweb\n```\n\n| Need | Command |\n|---|---|\n| Install and link `sweb` globally | `mint install 1amageek/swift-web@0.6.4 sweb` |\n| Run without linking | `mint run 1amageek/swift-web@0.6.4 sweb \u003ccommand\u003e` |\n| Print the installed executable path | `mint which 1amageek/swift-web@0.6.4 sweb` |\n\n```bash\nmint install 1amageek/swift-web@0.6.4 sweb\nsweb --help\nsweb new MyApp --output ../MyApp\n```\n\n## Usage\n\n### 1. Run The CLI From This Repository\n\nWhen developing SwiftWeb itself, clone the repository and run the CLI from the\ncheckout:\n\n```bash\ngit clone https://github.com/1amageek/swift-web.git\ncd swift-web\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb --help\n```\n\n### 2. Create An App\n\nGenerate a new app package next to the SwiftWeb checkout:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb new MyApp --output ../MyApp\n```\n\nThe default app has this shape:\n\n```text\nMyApp\n├─ Package.swift\n├─ Sources/MyApp/App.swift\n├─ Sources/MyApp/Routes/HomePage.swift\n└─ .swiftweb/generated\n   ├─ server\n   ├─ dev\n   └─ wasm\n```\n\nGenerate a chat-first app shell for AI work:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb new Chat --ai --output ../Chat\n```\n\nThe AI template adds a SwiftWebUI chat surface:\n\n```text\nChat\n├─ Package.swift\n├─ Sources/Chat/App.swift\n├─ Sources/Chat/Routes/ChatPage.swift\n├─ Sources/Chat/Components/ChatPanel.swift\n└─ .swiftweb/generated\n   ├─ server\n   ├─ dev\n   └─ wasm\n```\n\nThe app package depends on the SwiftWeb `main` branch and released `swift-html 0.7.1`.\n`sweb new` also materializes the generated launchers, dev packages, server packages,\nand WASM packages under `.swiftweb/generated`. Use `sweb prepare` only when you want\nto refresh generated packages for an existing SwiftWeb app without building or\nrunning it:\n\nApply a deployment platform adapter by preset or GitHub repository slug:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb new Chat --ai --platform cloudflare --output ../Chat\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb new Chat --ai --platform 1amageek/swift-web-cloudflare --output ../Chat\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb new Chat --ai --platform 1amageek/swift-web-cloudflare/chat --output ../Chat\n```\n\n`cloudflare` resolves to `1amageek/swift-web-cloudflare`. `sweb new` clones the\nadapter repository, validates `sweb.json`, copies the selected template\nfiles into the app package, renders `{{app.*}}` placeholders, and records the source\nin `.swiftweb/platform.json`. Custom platform template repositories can be referenced\nas `owner/repo` when they implement the platform adapter template contract. Add a\npath after the repository, such as `owner/repo/chat`, to select a named template\ninside that adapter repository.\nThe contract is documented in\n[`docs/PlatformAdapterTemplateContract.md`](docs/PlatformAdapterTemplateContract.md).\n\n```bash\ncd ../MyApp\nsweb prepare\n```\n\n### 3. Open The Xcode Package\n\nFrom the app package directory:\n\n```bash\nsweb xcode\n```\n\n`sweb xcode` runs the same materialization step as `sweb prepare`, then opens\n`.swiftweb/generated/dev` in Xcode.\n\nThe generated Xcode package includes a `\u003cAppName\u003e-dev` scheme that starts the same\ndevelopment runtime used by `sweb dev`.\n\n### 4. Run The Development Server\n\nFrom the app package directory:\n\n```bash\nsweb dev\n```\n\nOpen:\n\n```text\nhttp://127.0.0.1:3000/\n```\n\nThe dev command materializes `.swiftweb/generated`, builds the app server, starts the\nworker process, watches source changes, and sends browser update events.\n\n```mermaid\nflowchart LR\n  A[\"sweb dev\"] --\u003e B[\"materialize generated package\"]\n  B --\u003e C[\"build app server\"]\n  C --\u003e D[\"run worker\"]\n  D --\u003e E[\"watch files\"]\n  E --\u003e F[\"browser update\"]\n```\n\n### 5. Add Routes\n\n`Sources/MyApp/App.swift` mounts pages:\n\n```swift\nimport SwiftWeb\n\npublic struct MyApp: App {\n    public init() {}\n\n    public var body: some Scene {\n        HomePage()\n    }\n}\n```\n\n`Sources/MyApp/Routes/HomePage.swift` defines the route:\n\n```swift\nimport SwiftHTML\nimport SwiftWeb\n\n@Page(\"/\")\nstruct HomePage {\n    func body() -\u003e some HTML {\n        div {\n            h1 { \"Hello SwiftWeb\" }\n            p { \"Rendered by SwiftHTML and served through SwiftWeb.\" }\n        }\n    }\n}\n```\n\nAdd another route by creating another `@Page` type and mounting it from `App.body`:\n\n```swift\n@Page(\"/about\")\nstruct AboutPage {\n    func body() -\u003e some HTML {\n        main {\n            h1 { \"About\" }\n            p { \"This page is rendered on the server.\" }\n        }\n    }\n}\n```\n\n```swift\npublic var body: some Scene {\n    HomePage()\n    AboutPage()\n}\n```\n\nUse `PageGroup` when a set of pages shares a path prefix:\n\n```swift\npublic var body: some Scene {\n    HomePage()\n\n    PageGroup(\"admin\") {\n        AdminDashboardPage()\n        AdminUsersPage()\n    }\n}\n```\n\n### 6. Read The Request Session\n\nUse `@Session` inside request-time surfaces such as page bodies and server actions.\nThe wrapped value is `WebSession`, not a raw host request object.\n\n```swift\n@Page(\"/account\")\nstruct AccountPage {\n    @Session var session\n\n    func body() -\u003e some HTML {\n        if session.isAuthenticated {\n            AccountView()\n        } else {\n            LoginView()\n        }\n    }\n}\n```\n\n| Session API | Meaning |\n|---|---|\n| `session.isAuthenticated` | Reads SwiftWeb's authentication marker or stored `userID`. |\n| `session.userID` | Reads the stored user identifier. |\n| `session[\"key\"]` | Reads or writes string session state. |\n| `session.authenticate(userID:)` | Stores the user identifier and marks the session authenticated. |\n| `session.clearAuthentication()` | Removes SwiftWeb authentication keys. |\n| `session.destroy()` | Invalidates the current persisted session. |\n\n`@Session` is request-scoped. Do not read it from `App.body` or `Scene.body`, because\nthose build app topology without an active request. Scene-level access control belongs\nto route policy descriptors such as the planned `.restrict(...)` modifier.\n\n```swift\npublic var body: some Scene {\n    PageGroup(\"admin\") {\n        AdminDashboardPage()\n    }\n    // Target route-policy shape; this is a request-time descriptor.\n    // .restrict(.authenticated, redirectTo: \"/login\")\n}\n```\n\n### 7. Use SwiftWebUI Components\n\nImport `SwiftWebUI` when you want the higher-level component layer:\n\n```swift\nimport Foundation\nimport SwiftHTML\nimport SwiftWeb\nimport SwiftWebUI\n\n@Page(\"/\")\nstruct HomePage {\n    func body() -\u003e some HTML {\n        main {\n            GridSystem {\n                Pane(span: 12) {\n                    VStack(spacing: .medium) {\n                        Text(\"Hello SwiftWeb\")\n                            .font(.title)\n\n                        Link(\"Continue\", destination: URL(string: \"/about\")!)\n                            .buttonStyle(.borderedProminent)\n                    }\n                }\n            }\n            .frame(maxWidth: 720)\n        }\n    }\n}\n```\n\nSwiftWebUI lowers into the SwiftHTML graph. It does not replace SwiftHTML; raw SwiftHTML\nelements remain available when you need exact HTML control.\n\n### 8. Inspect Components With Storyboard\n\nRun the SwiftWebUI component Storyboard from the SwiftWeb checkout:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb storyboard\n```\n\nOpen:\n\n```text\nhttp://127.0.0.1:3001/storyboard\n```\n\nStoryboard generates an isolated package under `.swiftweb/storyboard`; it does not edit\nyour app package.\n\nRun Storyboard with production WASM artifacts and compression sidecars:\n\n```bash\n\"$SWIFT_WEB_HOST_SWIFT\" run sweb storyboard \\\n  --production \\\n  --runtime standard \\\n  -c release\n```\n\nThis path builds the generated Storyboard WASM runtime through the production artifact\nprocessor, writes `.wasm.gz` and `.wasm.br`, then starts the production `app-server`.\nSwiftWeb supports the standard WASM profile for Storyboard production validation.\n\n### 9. Build For Production\n\nBuild the generated server package:\n\n```bash\nsweb build\n```\n\nBuild browser WASM artifacts:\n\n```bash\nexport SWIFT_WEB_TOOLCHAIN_BIN=\"$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin\"\nexport SWIFT_WEB_HOST_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_TOOLCHAIN_BIN=\"$SWIFT_WEB_TOOLCHAIN_BIN\"\n\nsweb build \\\n  --wasm \\\n  --swift-sdk swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm \\\n  -c release\n```\n\nSwiftWeb's browser support boundary is the standard Swift WASM SDK:\n\n| Runtime profile | Support | Browser artifact shape |\n|---|---|---|\n| `standard` | Supported. Full `ClientComponent` hydration, client state, browser events, and SwiftWebUI runtime behavior. | App client source, `SwiftHTML`, `SwiftWebUI`, `SwiftWebUIRuntime`, `SwiftWebActors`, JavaScriptKit. |\n| Embedded Swift WASM | Not supported. Current Swift SDK and runtime dependencies do not provide the required `Distributed`, `Codable`, and Foundation capabilities for SwiftWeb's browser graph. | No public artifact contract. |\n\nProduction WASM builds strip debug/producers sections, optionally run `wasm-opt -Oz`,\nwrite `\u003cartifact\u003e.wasm.size.json`, and create cached `.gz` / `.br` sidecars.\nSwiftPM 6.4 places the release artifacts under:\n\n```text\n.swiftweb/generated/.build/wasm/out/Products/Release-webassembly-wasm32/\n  \u003cproduct\u003e.wasm\n  \u003cproduct\u003e.wasm.size.json\n  \u003cproduct\u003e.wasm.compression.json\n  \u003cproduct\u003e.wasm.gz\n  \u003cproduct\u003e.wasm.br\n```\n\n### 10. Try The Examples\n\nThe repository includes a minimal hello world app and a counter app with server\nactions, page invalidation, and a client-side counter component.\n\nRun the minimal app:\n\n```bash\ncd Examples/HelloWorld\nsweb dev\n```\n\nOpen:\n\n```text\nhttp://127.0.0.1:3000/\n```\n\nRun the counter app:\n\n```bash\ncd Examples/CounterApp\nsweb dev\n```\n\nOpen:\n\n```text\nhttp://127.0.0.1:3000/counter\n```\n\n## CLI\n\n| Command | Purpose |\n|---|---|\n| `sweb new \u003cAppName\u003e` | Generate a minimal SwiftWeb app package. |\n| `sweb new \u003cAppName\u003e --ai` | Generate a chat-first SwiftWebUI app shell for AI interfaces. |\n| `sweb new \u003cAppName\u003e --platform cloudflare` | Apply a preset deployment adapter template. |\n| `sweb new \u003cAppName\u003e --platform owner/repo` | Apply a GitHub-backed custom platform adapter template. |\n| `sweb new \u003cAppName\u003e --platform owner/repo/template` | Apply a custom platform adapter and named template path. |\n| `sweb prepare` | Materialize generated server, dev, and WASM packages for an existing app. |\n| `sweb xcode` | Materialize generated packages and open the dev package in Xcode. |\n| `sweb dev` | Run the development server with generated packages and HMR. |\n| `sweb storyboard` | Run the SwiftWebUI component Storyboard. |\n| `sweb build` | Build the generated production server package. |\n| `sweb build --wasm` | Build browser WASM runtime artifacts and production sidecars. |\n\nPackage commands default to the current directory. Run them from the directory that\ncontains `Package.swift`, or pass `--package-path` when targeting a package from\nanother directory.\n\n`sweb dev` uses a compact color console for dev status, rebuilds, HMR, and common\nerrors. It honors `NO_COLOR`; set `SWIFT_WEB_LOG_STYLE=plain` to keep the underlying\nswift-log output.\n\n## Development Workflow With sweb\n\nUse `sweb` from inside the application package. The CLI treats the directory that\ncontains `Package.swift` as the app root, materializes generated packages under\n`.swiftweb/generated`, and keeps your editable source under `Sources/\u003cAppName\u003e`.\n\n```mermaid\nflowchart LR\n  A[\"edit app sources\"] --\u003e B[\"sweb dev\"]\n  B --\u003e C[\"materialize .swiftweb/generated\"]\n  C --\u003e D[\"build server package\"]\n  D --\u003e E[\"run worker\"]\n  E --\u003e F[\"browser reload/HMR\"]\n  F --\u003e A\n```\n\n| Step | Command | When to use it |\n|---|---|---|\n| Create an app | `sweb new MyApp --output ../MyApp` | Start a new SwiftWeb package and materialize `.swiftweb/generated`. |\n| Create an AI chat app | `sweb new Chat --ai --output ../Chat` | Start with a SwiftWebUI chat page and client-side composer. |\n| Apply a Cloudflare adapter | `sweb new Chat --ai --platform cloudflare --output ../Chat` | Copy the selected template and record `1amageek/swift-web-cloudflare` in `.swiftweb/platform.json`. |\n| Apply a custom adapter | `sweb new App --platform owner/repo --output ../App` | Use any GitHub repository that implements the platform adapter template contract. |\n| Apply an adapter template | `sweb new Chat --platform 1amageek/swift-web-cloudflare/chat --output ../Chat` | Use the `chat` template from that platform adapter repository. |\n| Refresh generated packages | `sweb prepare` | Refresh `.swiftweb/generated` for an existing app without starting the server. |\n| Open the generated dev package | `sweb xcode` | Inspect or debug the generated development package in Xcode. |\n| Run the dev loop | `sweb dev` | Start the server, watcher, rebuild loop, and browser updates. |\n| Build the server package | `sweb build` | Validate the generated production server package. |\n| Build browser WASM | `sweb build --wasm --swift-sdk swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm -c release` | Produce optimized browser runtime artifacts and compression sidecars. |\n\nThe normal loop is:\n\n```bash\ncd MyApp\nsweb dev\n```\n\nThen edit route, component, and client island source files in `Sources/MyApp`.\nGenerated packages are implementation output; inspect them when debugging, but keep\nsource changes in the app package or in SwiftWeb itself.\n\nFor Xcode-based debugging, run:\n\n```bash\ncd MyApp\nsweb xcode\n```\n\nThis opens `.swiftweb/generated/dev`, whose `\u003cAppName\u003e-dev` scheme runs the same\ndevelopment runtime as `sweb dev`.\n\nBefore release-oriented checks, run:\n\n```bash\ncd MyApp\nsweb build\nexport SWIFT_WEB_TOOLCHAIN_BIN=\"$HOME/Library/Developer/Toolchains/swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a.xctoolchain/usr/bin\"\nexport SWIFT_WEB_HOST_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_SWIFT=\"$SWIFT_WEB_TOOLCHAIN_BIN/swift\"\nexport SWIFT_WEB_WASM_TOOLCHAIN_BIN=\"$SWIFT_WEB_TOOLCHAIN_BIN\"\nsweb build --wasm --swift-sdk swift-6.4.x-DEVELOPMENT-SNAPSHOT-2026-07-17-a_wasm -c release\n```\n\n## Browser Runtime\n\nSwiftWeb browser runtime packages copy runtime-only sources into generated WASM packages:\n\n| Runtime source | Browser WASM behavior |\n|---|---|\n| SwiftHTML | Runtime source copy; preview/doc sources are excluded. |\n| SwiftWebUI | Runtime source copy for client components. |\n| SwiftWebUIRuntime | JavaScriptKit-backed browser adapter. |\n| JavaScriptKit | Runtime-only copy; BridgeJS macros are not included by default. |\n| SwiftSyntax | Not included in generated browser runtime packages. |\n\n`sweb build --wasm` uses the standard Swift WASM compiler profile. SwiftWeb does\nnot expose Embedded Swift WASM as a supported runtime profile. Embedded Swift can\nbe revisited only if the browser runtime can be expressed without `Distributed`,\n`Codable`, Foundation, or profile-specific source families.\n\nThe intended production split is:\n\n```mermaid\nflowchart LR\n  A[\"Production page\"] --\u003e B{\"Browser behavior\"}\n  B --\u003e|\"client state / client events\"| C[\"standard WASM runtime\"]\n  B --\u003e|\"server-rendered / server actions\"| D[\"HTML + HTTP actions\"]\n  C --\u003e E[\".wasm + .gz + .br sidecars\"]\n  D --\u003e F[\"no separate Embedded Swift profile\"]\n```\n\nHistorical Embedded Swift measurements are research notes only and are not part of\nthe public support contract.\n\n### Client Bundles\n\n`ClientComponent` values are lowered into WASM bundles by contract. The default\ncontract joins the eager main bundle:\n\n```swift\npublic struct ClientSummary: ClientComponent {\n    @State private var count = 0\n\n    public init() {}\n\n    public var body: some HTML {\n        Button(\"Count \\(count)\") {\n            count += 1\n        }\n    }\n}\n```\n\nUse `loadPolicy` to decide when the browser loads a client island, and `bundle`\nto decide which logical bundle groups related islands:\n\n```swift\npublic struct ClientChart: ClientComponent {\n    public static let loadPolicy: LoadPolicy = .visible\n    public static let bundle: BundlePolicy = .named(\"analytics\")\n\n    public init() {}\n\n    public var body: some HTML {\n        GroupBox {\n            Text(\"Chart\").as(.h2)\n            Text(\"Loaded when the chart approaches the viewport.\").foregroundStyle(.secondary)\n        }\n    }\n}\n```\n\nPage-local overrides can be written where the client island is used:\n\n```swift\nClientInspector()\n    .loadPolicy(.manual)\n    .bundle(.shared(\"tools\"))\n```\n\n| Policy | Purpose |\n|---|---|\n| `.main` | Keep small or common eager components in the initial runtime. |\n| `.component` | Split one large isolated client island. |\n| `.named(\"analytics\")` | Group page or app features under a readable bundle name. |\n| `.shared(\"workspace\")` | Group reusable client components that should share one bundle. |\n\n| Load policy | Browser behavior |\n|---|---|\n| `.eager` | Load and instantiate during initial runtime startup. |\n| `.visible` | Load when the island approaches the viewport. |\n| `.interaction` | Load on hover, focus, touch, press, or click intent. |\n| `.idle` | Load during a browser idle window. |\n| `.manual` | Wait for an explicit runtime request. |\n\nModifiers must be attached to the outermost `ClientComponent` island. Nested\nclient components share the outer island's bundle contract. The default WASM\nsplit strategy coalesces non-eager bundles by load policy, while\n`SWIFTWEB_WASM_SPLIT_BUILD_STRATEGY=resolved` builds one artifact per resolved\nlogical bundle. See [ClientBundleLoadingDesign](docs/ClientBundleLoadingDesign.md)\nfor the full design.\n\nProduction WASM builds generate `.wasm.gz` and `.wasm.br` sidecars. Brotli defaults to\nquality 11 for production transfer size, and sidecars are cached by the post-processed\nWASM content hash so unchanged artifacts are not recompressed.\n\n## Development Notes\n\n| Topic | Current contract |\n|---|---|\n| Swift version | Keep `Package.swift` at `// swift-tools-version: 6.4`. |\n| `swift-html` | Released dependency: `0.11.1`. Storyboard development can still use a local sibling checkout when present. |\n| Host compatibility | The `swift-http-server` host stack uses the pinned Swift 6.4 snapshot (see Why Swift 6.4). |\n| WASM compatibility | Browser builds use the matching standard SDK. The matching Embedded SDK is pinned for capability validation but is not a public SwiftWeb browser profile. |\n| Versioned SwiftPM release | Released: every dependency resolves behind a version requirement as of `0.6.0`. |\n\n## License\n\nSwiftWeb is released under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1amageek%2Fswift-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1amageek%2Fswift-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1amageek%2Fswift-web/lists"}