Swift WASM Development Skill

Comprehensive support for Swift 6.2 WebAssembly development using official toolchains, Carton, and modern WASM APIs.

Quick Actions

When invoked with arguments:

•setup - Set up Swift 6.2.3 + WASM SDK or Carton
•build - Build the current project for WASM
•dev - Start development server with hot reload
•optimize - Build optimized production bundle
•debug - Debug WASM build issues
•test - Run tests in browser

When invoked without arguments or when the user asks about Swift WASM:

•Analyze their needs and provide appropriate guidance
•Reference existing documentation in the project
•Execute appropriate commands

Project Documentation

This project has excellent existing documentation:

•NATIVE_WASM_SETUP.md - Official Swift 6.2.3 + WASM SDK setup
•CARTON_WORKFLOW.md - Complete Carton development workflow
•QUICKSTART.md - Getting started guide

Always reference these docs when helping users.

Swift 6.2 WASM Key Facts (2026)

Official Support

•Swift 6.2+ includes native WebAssembly support (no custom forks needed)
•Two SDK variants: swift-6.2.3-RELEASE_wasm (full stdlib) and swift-6.2.3-RELEASE_wasm-embedded (tiny)
•Target triple: wasm32-unknown-wasip1 (newer than wasm32-unknown-wasi)
•Official distribution via swift.org

Tooling Options

Option 1: Official Swift 6.2.3 + WASM SDK (Production)

•Latest Swift with official WASM support
•~50MB SDK download
•Requires swiftly toolchain manager
•Best for production and CI/CD

Option 2: Carton (Development)

•All-in-one development tool
•Built-in dev server with hot reload
•Automatic SwiftWasm download
•Uses SwiftWasm 6.0.2 (slightly older)
•Best for rapid development

Key Libraries

•JavaScriptKit - Swift/JavaScript interop (currently 0.19.2 in this project)
•WasmKit - WebAssembly runtime in Swift (included with Swift 6.2+)
•BridgeJS - TypeScript to Swift code generation
•PackageToJS - Export Swift to JavaScript

Common Commands Reference

Setup Commands

bash

# Install swiftly (Swift toolchain manager)
brew install swiftly

# Install swift.org Swift 6.2.3
swiftly install 6.2.3
swiftly use 6.2.3

# Verify (should NOT say "Apple Swift")
swift --version

# Install WASM SDK
swift sdk install \
  https://download.swift.org/swift-6.2.3-release/wasm-sdk/swift-6.2.3-RELEASE/swift-6.2.3-RELEASE_wasm.artifactbundle.tar.gz \
  --checksum 394040ecd5260e68bb02f6c20aeede733b9b90702c2204e178f3e42413edad2a

# Verify SDK installation
swift sdk list

Build Commands

bash

# Native WASM build (debug)
swift build --swift-sdk swift-6.2.3-RELEASE_wasm

# Native WASM build (optimized production)
swift build --swift-sdk swift-6.2.3-RELEASE_wasm -c release -Xswiftc -Osize

# Carton development server
carton dev

# Carton production bundle
carton bundle --release

# Carton with size optimization
carton bundle --release -Xswiftc -Osize -Xswiftc -whole-module-optimization

Optimization Commands

bash

# Build with all optimizations
swift build \
  --swift-sdk swift-6.2.3-RELEASE_wasm \
  -c release \
  -Xswiftc -Osize \
  -Xswiftc -whole-module-optimization \
  -Xlinker --lto-O3 \
  -Xlinker --gc-sections \
  -Xlinker --strip-debug

# Post-process optimization (requires wasm-opt from binaryen)
wasm-opt -O3 input.wasm -o output.wasm

# Compress with Brotli
brotli -q 11 optimized.wasm

Development Commands

bash

# Start simple dev server
python3 -m http.server 8000

# Watch for changes (manual)
swift build --swift-sdk swift-6.2.3-RELEASE_wasm && python3 -m http.server 8000

# Check build output
ls -lh .build/wasm32-unknown-wasip1/release/

Testing Commands

bash

# Run tests with Carton
carton test

# Run tests in specific browser
carton test --environment chrome
carton test --environment firefox
carton test --environment safari

Workflow Patterns

Pattern 1: Quick Development (Carton)

bash

# One-time setup
echo "wasm-6.0.2-RELEASE" > .swift-version

# Daily workflow
carton dev
# Edit Sources/*.swift
# Browser auto-refreshes on save

Pattern 2: Production Build (Official SDK)

bash

# Ensure using swift.org toolchain
swiftly use 6.2.3

# Build optimized
swift build --swift-sdk swift-6.2.3-RELEASE_wasm -c release -Xswiftc -Osize

# Serve for testing
python3 -m http.server 8000

Pattern 3: CI/CD Pipeline

bash

# Install toolchain
swiftly install 6.2.3
swiftly use 6.2.3

# Install SDK
swift sdk install <URL> --checksum <CHECKSUM>

# Build
swift build --swift-sdk swift-6.2.3-RELEASE_wasm -c release

# Deploy .build/wasm32-unknown-wasip1/release/*.wasm

Troubleshooting Guide

"No available targets compatible with wasm32-unknown-wasip1"

Cause: Using Apple's Xcode Swift instead of swift.org Swift

Solution:

bash

brew install swiftly
swiftly install 6.2.3
swiftly use 6.2.3
swift --version  # Should NOT say "Apple"

Build is Slow

Cause: First build compiles all dependencies

Solutions:

•Use debug builds during development: swift build --swift-sdk swift-6.2.3-RELEASE_wasm
•Use Carton for incremental builds: carton dev
•Cache .build/ directory in CI/CD

WASM File Too Large

Typical sizes:

•Debug: 3-5 MB
•Release: 800KB - 1.5 MB
•Release + Osize: 400-600 KB
•Brotli compressed: 150-250 KB

Solutions:

•Use -Xswiftc -Osize flag
•Enable link-time optimization: -Xlinker --lto-O3
•Strip debug symbols: -Xlinker --strip-debug
•Use wasm-opt: wasm-opt -O3 input.wasm -o output.wasm
•Compress with Brotli for serving

Carton vs Native SDK Issues

Problem: Mixed Swift versions (Raven built with 6.2, app with 6.0)

Solution: Usually fine (ABI compatible), but for best results:

•Development: Use Carton (easier)
•Production: Use native SDK (latest features)
•CI/CD: Use native SDK (reproducible)

JavaScriptKit Version Mismatch

Current project: Pinned to JavaScriptKit 0.19.2 for Swift 6.0 compatibility

If upgrading:

•Check SwiftWasm compatibility matrix
•Test thoroughly before upgrading
•Latest is 0.33.0+ (Feb 2026)

Page Shows "Loading..." Forever

Debugging steps:

•Open browser console (Cmd+Option+I)
•
Check for errors:
- •404: WASM file not found (check path)
- •MIME type: Server not serving .wasm correctly
- •Instantiation: WASM runtime error
•Verify WASM file exists: ls -lh .build/wasm32-unknown-wasip1/*/YourApp.wasm
•Check file size (should be >100KB for real apps)

Performance Best Practices

Binary Size

•Use -Osize for size optimization
•Avoid heavy dependencies
•Enable whole-module optimization
•Use embedded SDK for size-critical apps
•Post-process with wasm-opt

Load Time

•Compress with Brotli (3x smaller)
•Use CDN for JavaScriptKit runtime
•Preload WASM file: <link rel="preload" href="/app.wasm" as="fetch" crossorigin>
•Enable HTTP/2 or HTTP/3
•Use streaming compilation: WebAssembly.instantiateStreaming()

Runtime Performance

•Minimize Swift/JS bridging calls
•Batch DOM updates
•Use async/await for non-blocking operations
•Profile with Chrome DevTools

Development Speed

•Use Carton for hot reload
•Debug builds for faster iteration
•Release builds only for production
•Cache dependencies

Debugging Techniques

Browser DevTools

Enable DWARF support in Chrome:

•Build with debug info: swift build --swift-sdk swift-6.2.3-RELEASE_wasm -c debug
•Open Chrome DevTools
•Sources tab → Enable DWARF support
•Set breakpoints in Swift source
•Step through code with full variable inspection

Console debugging:

swift

import JavaScriptKit

// Log to browser console
let console = JSObject.global.console
console.log("Debug message:", someValue)

LLDB Debugging

Swift 6.2 includes LLDB WebAssembly support:

bash

# Build with debug symbols
swift build --swift-sdk swift-6.2.3-RELEASE_wasm -c debug

# Use WasmKit for debugging
# (Integration with LLDB for WASM targets)

Performance Profiling

bash

# Chrome DevTools Performance tab
# Record → Interact with app → Stop → Analyze

# Memory profiling
# Chrome DevTools Memory tab → Take heap snapshot

Deployment Platforms

Static Hosts (Recommended)

•Netlify - Zero config, automatic deploys
•Vercel - Edge network, serverless functions
•GitHub Pages - Free, simple, version controlled
•Cloudflare Pages - Global CDN, fast edge deployment

Edge Computing

•Cloudflare Workers - Run WASM at the edge
•Fastly Compute - WASM-based edge compute

Cloud Storage + CDN

•AWS S3 + CloudFront - Scalable, full control
•Azure Static Web Apps - Integrated CI/CD
•Google Cloud Storage + CDN - Global distribution

Task Execution Logic

When invoked:

•Determine user intent from argument or question
•
Check current state:
- •Which Swift version? (swift --version)
- •Is WASM SDK installed? (swift sdk list)
- •Is Carton available? (carton --version)
- •What's in Package.swift? (read file)
•
Execute appropriate action:
- •Setup: Guide through installation
- •Build: Choose Carton vs native based on context
- •Dev: Start appropriate dev server
- •Optimize: Apply production optimizations
- •Debug: Diagnose and fix issues
- •Test: Run appropriate test suite
•Provide next steps and reference documentation

Example Interactions

User: "Set up Swift WASM"

•Check if swiftly is installed
•Install Swift 6.2.3 if needed
•Install WASM SDK
•Verify installation
•Point to NATIVE_WASM_SETUP.md for details

User: "Build my app"

•Check if Carton is available
•If yes and .swift-version exists: use Carton
•Otherwise: use native SDK build
•Display build output and file sizes
•Suggest next steps (serve, optimize, deploy)

User: "Why is my WASM file 5MB?"

•Check current build configuration
•Explain typical sizes
•Suggest optimization flags
•Run optimized build
•Compare before/after sizes

User: "Deploy to production"

•Build optimized bundle
•Show deployment options
•Provide example configs for common platforms
•Verify build output is ready

Reference Links

Notes for Claude

•Always check project docs first - NATIVE_WASM_SETUP.md, CARTON_WORKFLOW.md, QUICKSTART.md
•Verify before executing - Check Swift version, SDK availability, etc.
•Use appropriate tool - Carton for dev, native SDK for production
•Explain trade-offs - Speed vs size, debug vs release, Carton vs native
•Provide file references - Use file:line format for navigation
•Show actual output - Run commands and display results
•Suggest next steps - Don't leave users hanging
•Reference sizes - Always show before/after when optimizing
•Be platform-aware - macOS vs Linux differences in setup
•Check for updates - Swift WASM ecosystem evolves rapidly

Current Project Configuration

This Raven project uses:

•Swift 6.2.3 (.swift-version)
•JavaScriptKit 0.19.2 (pinned for compatibility)
•Platforms: macOS 13+, iOS 16+
•Optimized Package.swift with WASM flags

When helping with this project, respect these constraints and don't suggest breaking changes without discussion.