Getting Started with Server-Side Swift with Vapor 4

The dream of using the same language on the server that you use in your iOS apps is calling out to you! But maybe you’ve never done server-side work before? And you already know Swift? Good, you are in the right place :]

Beginning a project in a new domain and using a new technology can be daunting, but Vapor makes it easy to get started with server-side Swift. Vapor provides a handy command line tool to create a starter project for you.

In this tutorial, you’ll start by installing the Vapor Toolbox, then use it to build and run your first project. You’ll finish by learning about routing, accepting data and returning JSON.

Getting Started

The first step in beginning Vapor development is to install the Vapor Toolbox.

The Vapor Toolbox is a command line interface (CLI) tool you use when developing Vapor apps. It helps you create a new Vapor project from a template and allows to add dependencies as needed.

Before installing the toolbox, make ensure your system has Swift installed. On macOS, simply install Xcode from the Mac App Store. On Linux, download it from https://www.swift.org and install as described below.

Installing on macOS

Vapor uses Homebrew to install the Toolbox.

In Terminal run the following commands:

brew install vapor

To make sure Vapor is correctly installed run

vapor

and you should the following output:

> vapor
Usage: vapor <command>

Vapor Toolbox (Server-side Swift web framework)

Commands:
       build Builds an app in the console.
       clean Cleans temporary files.
      heroku Commands for working with Heroku
         new Generates a new app.
         run Runs an app from the console.
  supervisor Commands for working with Supervisord
       xcode Opens an app in Xcode.

Use `vapor <command> [--help,-h]` for more information on a command.
Error: Error: Missing command
>

That means Vapor is ready to rock :]

Installing on Linux

Everything you build with Vapor will work on versions of Linux that Swift supports. The Vapor Toolbox works in exactly the same way, with the exception that you can’t use Xcode on Linux.

To install Swift on Linux, go to https://swift.org/download/ and download the toolchain for your operating system. Follow the installation to install the toolchain on your machine. When complete, enter the following at a shell prompt:

swift --version

You should get the correct version of Swift returned:

Swift version 5.2.4 (swift-5.2.4-RELEASE)
Target: x86_64-unknown-linux-gnu

In your console, run the following commands:

# 1
git clone https://github.com/vapor/toolbox.git
# 2
cd toolbox
# 3
git checkout 18.0.0
# 4
swift build -c release --disable-sandbox --enable-test-discovery
# 5
mv .build/release/vapor /usr/local/bin

Here’s what this does:

1. Clone the toolbox from GitHub.
2. Navigate into the toolbox directory that you cloned.
3. Check out version 18.0.0. You can find the latest release of the toolbox on the releases page on GitHub.
4. Build the toolbox in release mode. --disable-sandbox allows the toolbox to execute other processes.
5. Move the toolbox into your local path so you can call it from anywhere. (You might need to prefix this command with sudo on some Linux distributions.)

This article uses Ubuntu 20.04 throughout when referring to Linux, but the other supported versions of Linux should work in exactly the same way.

Building Your First App

Setting up a Vapor project can seem complicated at first as there are a number of required files and directories. To help with this, the Toolbox can create a new project from a template. It can generate projects for a simple API, websites and authentication. You can even create your own templates.

First, create a new directory in your home directory or somewhere sensible to work on your Vapor projects. For example, enter the following commands in Terminal:

mkdir ~/vapor
cd ~/vapor

This creates a new directory in your home folder called vapor and navigates you there. Next, create your project with:

vapor new HelloVapor

The toolbox then asks if you’d like to use Fluent. For now, type n followed by Enter. You’ll learn about Fluent in a future tutorial. The toolbox then generates your project for you.

You should see the following:

To build and start your app, run:

# 1
cd HelloVapor
# 2
swift run

Here’s what this does:

1. cd is the “Change Directory” command and takes you into the project directory.
2. This builds and runs the app. The first time you run it, it can take some time since it must fetch all the dependencies.

The template has a predefined route, so open your browser and visit http://localhost:8080/hello and see the response!

Now press Control-C in Terminal to stop the running app.

Swift Package Manager

Vapor Toolbox uses Swift Package Manager, or SwiftPM, — a dependency management system similar to CocoaPods on iOS — to configure and build Vapor apps. Open your project directory and look at the structure. On macOS in Terminal, enter:

open .

Notice there’s no Xcode project in your template even though you’ve built and run the app. This is deliberate. In fact, the project file is explicitly excluded from source control using the .gitignore file. When using SwiftPM, Xcode creates a workspace in a hidden directory called .swiftpm.

A SwiftPM project is defined in the Package.swift manifest file. It declares targets, dependencies and how they link together. The project layout is also different from a traditional Xcode project. There is a Tests directory for tests. There is a Sources directory for source files. Each module defined in your manifest has its own directory inside Sources. Your sample app has an App module and a Run module, so Sources contains an App directory and a Run directory.

Inside the Run directory, there’s a single file: main.swift. This is the entry point required by all Swift apps.

The template contains everything you need to set up your app and you shouldn’t need to change main.swift or the Run module. Your code lives in App or any other modules you define.