server-side-swift

name	server-side-swift
description	Server-side Swift development with Vapor and Hummingbird. Covers project setup, routing, Fluent ORM, authentication, deployment, and shared client-server code. Use when building backends or APIs in Swift.
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","AskUserQuestion"]

Server-Side Swift Generator

Generates and guides server-side Swift projects using Vapor or Hummingbird, including API design, database integration, authentication, deployment, and shared code with iOS clients.

When This Skill Activates

Use this skill when the user:

• Asks to "create a backend" or "build an API" in Swift
• Mentions "Vapor", "Hummingbird", or "server-side Swift"
• Wants JWT, OAuth, or session authentication on the server
• Needs to share Codable models between an iOS app and a Swift server
• Asks about sending push notifications from a server (APNSwift)
• Wants to deploy a Swift server (Docker, Fly.io, Railway)
• Mentions Fluent ORM, database migrations, or PostgreSQL with Swift
• Asks about WebSockets or real-time features on the server
• Wants to replace CloudKit with a custom backend

Pre-Generation Checks

1. Project Context Detection

• Check if a Package.swift already exists
• Determine if this is a new project or adding to an existing one
• Check Swift version (async/await requires Swift 5.5+, Hummingbird 2 requires Swift 6+)
• Search for existing server-side code

Glob: **/Package.swift, **/configure.swift, **/routes.swift, **/entrypoint.swift
Grep: "import Vapor" or "import Hummingbird" or "import Fluent"

2. Conflict Detection

Search for existing server implementations:

Glob: **/Controllers/*.swift, **/Migrations/*.swift, **/Models/*.swift
Grep: "RouteCollection" or "AsyncMigration" or "func routes"

If found, ask user:

• Extend existing server with new endpoints?
• Replace existing implementation?

3. iOS Client Detection

Check if an iOS client exists in the workspace:

Glob: **/*.xcodeproj, **/*.xcworkspace
Grep: "import SwiftUI" or "import UIKit"

If found, recommend SharedModels package pattern.

Architecture Decision Gate

Before asking about framework choice, validate that server-side Swift is the right technology for this project. Reference architecture-decisions.md for the full decision framework.

Quick Validation (ask yourself, not the user)

1. Does the user have a Swift team or iOS app? → If no, surface alternatives (Go, Node.js, Python)
2. Does client-server code sharing provide value? → Strongest signal for Swift
3. Does the project need integrations Swift lacks (Kafka, Elasticsearch, email)? → Surface ecosystem gaps honestly

If any red flags, present trade-offs from architecture-decisions.md before proceeding. Example:

"Before we start — server-side Swift works best when you have an iOS app that can share models with the backend. Since your project is [web-only / cross-platform / ML-heavy], you might want to consider [Node.js / Go / Python] instead. Want me to explain the trade-offs, or proceed with Swift?"

If "Help me decide" on Vapor vs Hummingbird

Don't default arbitrarily. Ask about context:

• Team size and experience — New to server Swift? → Vapor (more docs, bigger community)
• Project type — Lambda/microservice? → Hummingbird (smaller binary, first-class Lambda)
• Compile time sensitivity — Tight CI/CD? → Hummingbird (lighter dependency graph)
• Feature needs — Need ORM + auth + WebSocket out of the box? → Vapor

Reference the weighted decision matrix in architecture-decisions.md for detailed comparison.

Configuration Questions

Ask user via AskUserQuestion:

1. Which framework do you want to use?

   • Vapor (batteries-included, Fluent ORM, larger community — 78% market share)
   • Hummingbird (lightweight, pure structured concurrency, modular — ideal for microservices/Lambda)
   • Help me decide (I'll ask about your project context)

2. What database do you need?

   • PostgreSQL (recommended for production)
   • SQLite (development/lightweight)
   • None (stateless API)
   • MongoDB

3. What authentication method?

   • JWT (stateless, recommended for mobile APIs)
   • Session-based (web apps)
   • Sign in with Apple (server-side validation)
   • Bearer token (simple)
   • None

4. Do you need shared models with an iOS client?

   • Yes, create a SharedModels package
   • No, server-only project

Generation Process

Step 1: Project Scaffolding

Generate the project structure based on framework choice:

Vapor:

Sources/App/
├── Controllers/
├── Migrations/
├── Models/
├── DTOs/
├── configure.swift
├── entrypoint.swift
└── routes.swift
Tests/AppTests/
Package.swift
Dockerfile
docker-compose.yml
.env
.gitignore

Hummingbird:

Sources/App/
├── Controllers/
├── Models/
├── Application+build.swift
└── App.swift
Tests/AppTests/
Package.swift
Dockerfile

Step 2: Core Files

Generate based on configuration:

1. Package.swift - Dependencies for chosen framework + database + auth
2. configure.swift / Application+build.swift - App configuration
3. Entry point with environment detection
4. Basic health check endpoint

Step 3: Database Layer (if selected)

1. Model files with Fluent property wrappers
2. Migration files with AsyncMigration
3. Database configuration in configure.swift

Step 4: Authentication (if selected)

1. Auth middleware and authenticators
2. Token/session model and migration
3. Protected route groups
4. Login/register endpoints

Step 5: Shared Models (if selected)

1. SharedModels/ package with DTOs
2. Update both Package.swift files to depend on SharedModels
3. API endpoint protocol definitions

Step 6: Deployment Files

1. Multi-stage Dockerfile
2. docker-compose.yml with database service
3. .env template with required variables

Swift 6 Concurrency Notes

Vapor 4 Async/Await

All new code should use async/await exclusively:

app.get("users") { req async throws -> [User] in
    try await User.query(on: req.db).all()
}

Hummingbird 2 Pure Concurrency

Hummingbird 2 is built entirely on structured concurrency with no EventLoopFuture APIs:

router.get("users") { request, context async throws -> [UserDTO] in
    try await userRepository.findAll()
}

Sendable Compliance

All DTOs shared between client and server must be Sendable:

public struct UserDTO: Codable, Sendable {
    public let id: UUID?
    public let name: String
    public let email: String
}

Output Format

Files Created

YourProject/
├── Sources/App/
│   ├── Controllers/
│   │   └── TodoController.swift    # Route collection
│   ├── Migrations/
│   │   └── CreateTodo.swift        # Database migration
│   ├── Models/
│   │   └── Todo.swift              # Fluent model
│   ├── DTOs/
│   │   └── TodoDTO.swift           # Request/response DTO
│   ├── configure.swift             # App configuration
│   ├── entrypoint.swift            # Entry point
│   └── routes.swift                # Route registration
├── Tests/AppTests/
│   └── TodoTests.swift             # Integration tests
├── Package.swift                   # Dependencies
├── Dockerfile                      # Multi-stage build
├── docker-compose.yml              # App + database
└── .env                            # Environment variables

Integration Steps

Run locally:

# Start database
docker-compose up db -d

# Run migrations
swift run App migrate --yes

# Start server
swift run App serve --hostname 0.0.0.0 --port 8080

Connect from iOS client:

let client = URLSessionAPIClient(
    configuration: .init(baseURL: URL(string: "http://localhost:8080/api/v1")!)
)
let todos = try await client.request(ListTodosEndpoint())

Testing

@Suite("API Tests", .serialized)
struct TodoTests {
    @Test("Create todo returns 200")
    func createTodo() async throws {
        try await withApp(configure: configure) { app in
            let dto = TodoDTO(title: "Test")
            try await app.testing().test(.POST, "api/v1/todos", beforeRequest: { req in
                try req.content.encode(dto)
            }, afterResponse: { res async throws in
                #expect(res.status == .ok)
                let created = try res.content.decode(TodoDTO.self)
                #expect(created.title == "Test")
            })
        }
    }
}

References

• architecture-decisions.md - When to use server-side Swift, Vapor vs Hummingbird decision matrix, ecosystem gaps, pitfalls
• vapor-patterns.md - Routing, controllers, middleware, configuration
• hummingbird-patterns.md - Hummingbird 2 patterns and Vapor vs Hummingbird decision
• database-patterns.md - Fluent ORM, migrations, queries, relationships
• auth-patterns.md - JWT, sessions, Bearer, Sign in with Apple server-side
• deployment-patterns.md - Docker, Fly.io, Railway, production setup
• shared-code-patterns.md - SharedModels, DTOs, APNSwift
• testing-patterns.md - VaporTesting, Swift Testing, integration tests
• Vapor Documentation
• Hummingbird Documentation
• Swift on Server