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.
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.
Here I will go into a bit of detail of what is involved in the template.
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
- The project name, currently
- The name of the executable,
Appand the targets it requires
- The packages we are dependent on ie
hummingbirdand also Apple's
swift-argument-parserto ease reading of command line arguments.
- Two targets, the application
Appand the test project
App source code consists of two files.
App.swiftthis 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.
Application+configure.swiftwhich is where you configure your application, add routes, add middleware and any other general
HBApplicationsetup. There is one default route added
GET /healthwhich return
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
The project template also includes the following files.
Dockerfilefor building and running docker images of your project
.dockerignorefile containing folders you don't need to sync when building your docker images
.gitignorewith a list of standard files to not include in your project
README.mdfor 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!