Vapor framework guardrails, patterns, and best practices for AI-assisted development.
Use when working with Vapor projects, or when the user mentions Vapor.
Provides Fluent ORM, async Swift, routing, middleware, and server-side Swift guidelines.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Vapor framework guardrails, patterns, and best practices for AI-assisted development.
Use when working with Vapor projects, or when the user mentions Vapor.
Provides Fluent ORM, async Swift, routing, middleware, and server-side Swift guidelines.
Applies to: Vapor 4.x, Swift 5.9+, Fluent ORM, Leaf Templates, Server-Side Swift
Language Guide: @.claude/skills/swift-guide/SKILL.md
Overview
Vapor is a server-side Swift framework for building web applications, REST APIs, and backend services. It provides type-safe routing, Fluent ORM, async/await concurrency, JWT authentication, and Leaf templating.
Use Vapor when:
Building Swift-native backend services
Sharing code between iOS/macOS clients and the server
You need type-safe, compile-time-checked API development
You want async/await patterns throughout the stack
Consider alternatives when:
Team lacks Swift experience
You need a massive middleware ecosystem (consider Express, Rails)
Maximum raw performance is critical (consider Rust/Actix-web)
Guardrails
Vapor-Specific Rules
Use the @main entry point pattern with
Application.make
Group routes by resource with RouteCollection controllers
Use Fluent property wrappers (@ID, @Field, @Parent, @Children) for models
Use Content protocol for all request/response DTOs
Use Validatable protocol for input validation on every endpoint
Use AsyncMiddleware for cross-cutting concerns (auth, logging, CORS)
Use AsyncMigration with both prepare and revert methods
Configure databases from environment variables (never hardcode credentials)
Use DTOs to separate API contracts from database models
Implement pagination for all list endpoints
Use @Sendable on all route handler closures
Mark model classes as @unchecked Sendable (Fluent requirement)
Anti-Patterns
Do not expose Fluent models directly as API responses (use DTOs)
Do not put business logic in controllers (use a service layer)
Do not use autoMigrate in production (run migrations explicitly)
Do not skip revert in migrations (always provide rollback)
Do not use try! or fatalError in request handlers
Do not store request-scoped state in global variables
# Initialize project
swift package init --type executable --name MyVaporApp
# Resolve dependencies
swift package resolve
# Build and run
swift build
swift run App serve --hostname 0.0.0.0 --port 8080
# Run tests
swift test
swift test --filter AppTests
# Run database migrations manually
swift run App migrate
swift run App migrate --revert
# Docker build
docker build -t my-vapor-app .
docker compose up -d
Dependencies
Package
Purpose
vapor/vapor
Core web framework
vapor/fluent
ORM abstraction
vapor/fluent-postgres-driver
PostgreSQL support
vapor/fluent-sqlite-driver
SQLite (development/testing)
vapor/redis
Redis caching and sessions
vapor/jwt
JWT authentication
vapor/leaf
Template engine
XCTVapor
Testing utilities (included with Vapor)
Advanced Topics
For detailed patterns, WebSocket integration, Leaf templates, queues, testing, and deployment, see:
