A template for building Hummingbird applications

The Hummingbird server framework is designed to be flexible. It imposes as little structure as possible on how you build your application, but sometimes you need some structure. Do you really want to build all your application setup boilerplate every time you create a new app? To avoid this I have written a hummingbird project template which can be your starting point for your next app.

Template repository

GitHub has a feature called template repositories. These allow you to create a new project repository setup for a particular type of project. I have created a Hummingbird template here.

To create your Hummingbird project you go to the template project in GitHub and press the Use this template button. You now have the basis for building your next great server application.

Details

Here I will go into a bit of detail of what is involved in the template.

Package.Swift

The project is setup with the Swift Package Manager. The Package.swift file defines all the project dependencies and targets.

// swift-tools-version:5.5
import PackageDescription

let package = Package(
    name: "hummingbird-template",
    products: [
        .executable(name: "App", targets: ["App"]),
    ],
    dependencies: [
        .package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "0.15.0"),
        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.0.0")
    ],
    targets: [
        .executableTarget(name: "App",
            dependencies: [
                .product(name: "ArgumentParser", package: "swift-argument-parser"),
                .product(name: "Hummingbird", package: "hummingbird"),
            ],
            swiftSettings: [
                // Enable better optimizations when building in Release configuration. Despite the use of
                // the `.unsafeFlags` construct required by SwiftPM, this flag is recommended for Release
                // builds. See <https://github.com/swift-server/guides#building-for-production> for details.
                .unsafeFlags(["-cross-module-optimization"], .when(configuration: .release))
            ]
        ),
        .testTarget(name: "AppTests",
            dependencies: [
                .byName(name: "App"),
                .product(name: "HummingbirdXCT", package: "hummingbird")
            ]
        )
    ]
)

In this file you can see we have

1. The project name, currently hummingbird-template
2. The name of the executable, App and the targets it requires
3. The packages we are dependent on ie hummingbird and also Apple's swift-argument-parser to ease reading of command line arguments.
4. Two targets, the application App and the test project AppTests.

Source code

The App source code consists of two files.

1. App.swift this is the entrypoint for your application. It defines the commandline arguments and starts and stops your application. If you need to add more commandline arguments to your application do it here.
2. Application+configure.swift which is where you configure your application, add routes, add middleware and any other general HBApplication setup. There is one default route added GET /health which return .ok.

The AppTests source code consists of one set of tests AppTests.swift. It has one example test in there using the HummingbirdXCT framework to test the GET health route setup in your App.

Other files

The project template also includes the following files.

1. Dockerfile for building and running docker images of your project
2. .dockerignore file containing folders you don't need to sync when building your docker images
3. .gitignore with a list of standard files to not include in your project
4. README.md for you to tell everyone about your great project

This is all the boilerplate you should need to start your application. How you structure the rest of it is up to you. Now, let's get creating!