Getting Started with Swiftlets

1Clone and Build

First, ensure you have Swift installed (5.7 or later), then clone the Swiftlets repository and build the server:

# Clone the repository
git clone https://github.com/codelynx/swiftlets.git
cd swiftlets

# Build the server (one time setup)
./build-server

This builds the server binary and places it in the platform-specific directory (e.g., bin/macos/arm64/).

2Try the Showcase Site

Before creating your own project, let's explore what Swiftlets can do! The repository includes a complete example site with documentation and component showcases - all built with Swiftlets.

Build and run the example site:

# Build the site
./build-site sites/swiftlets-site

# Run the site
./run-site sites/swiftlets-site

# Or combine build and run
./run-site sites/swiftlets-site --build

Visit http://localhost:8080 and explore:

• /showcase - See all HTML components in action
• /docs - Read documentation (also built with Swiftlets!)
• View source - Check sites/swiftlets-site/src/ to see how it's built

3Understanding the Architecture

Swiftlets uses a unique architecture where each route is a standalone executable:

sites/swiftlets-site/
├── src/              # Swift source files
│   ├── index.swift   # Homepage route
│   ├── about.swift   # About page route
│   └── docs/
│       └── index.swift  # Docs index route
├── web/              # Static files + .webbin markers
│   ├── styles/       # CSS files
│   ├── *.webbin      # Route markers (generated)
│   └── images/       # Static assets
└── bin/              # Compiled executables (generated)
    ├── index         # Executable for /
    ├── about         # Executable for /about
    └── docs/
        └── index     # Executable for /docs

Key concepts:

• File-based routing: Your file structure defines your routes
• Independent executables: Each route compiles to its own binary
• No Makefiles needed: The build-site script handles everything
• Hot reload ready: Executables can be rebuilt without restarting the server

4Working with Sites

The build scripts make it easy to work with any site:

# Build a site (incremental - only changed files)
./build-site path/to/site

# Force rebuild all files
./build-site path/to/site --force

# Clean build artifacts
./build-site path/to/site --clean

# Run a site
./run-site path/to/site

# Run with custom port
./run-site path/to/site --port 3000

# Build and run in one command
./run-site path/to/site --build

5SwiftUI-Style Components

Swiftlets now supports a zero-boilerplate API with @main, inspired by SwiftUI:

@main
struct HomePage: SwiftletMain {
    @Query("name") var userName: String?
    
    var title = "Welcome"
    
    var body: some HTMLElement {
        VStack(spacing: 20) {
            H1("Hello, \(userName ?? "World")!")
            P("Welcome to Swiftlets")
                .style("font-size", "1.25rem")
        }
        .style("text-align", "center")
        .style("padding", "3rem")
    }
}

This approach enables building complex UIs from simple, composable components - just like SwiftUI!

Next Steps