Getting Started With Vapor

Written by Tim on Sunday, August 27, 2017

This is the start of a series of tutorials on Vapor. For more, click here

Vapor

Swift is Apple's programming language that was introduced at the 2014 Worldwide Developers Conference. A year later, in December 2015, it was open sourced and ever since that has been able to run on Linux. Since it was open sourced, a number of frameworks have been created to take advantage of its power and speed. One of those is Vapor and in this tutorial, you will learn how to get up and running with Vapor.

What is Vapor?

Vapor is a web framework that sits on top of Swift to allow you to easily write server-side applications. These could be APIs that you call from an iOS or Android app, or it could be a fully-fledged website, like Twitter. It is comparable to Flask or Django in Python, NodeJS in Javascript, or Ruby on Rails for Ruby.

Installing the Toolbox

Before we get into the concepts of Vapor, lets go ahead and install the Vapor toolbox. The toolbox wraps many of the Swift Package Manager commands to help create your projects and also provides extra features, such as creating a project from a template.

Note: This tutorial assumes that you are running on macOS using Xcode. Most of the instructions will apply on Linux, and all of the code will work, but some of the Xcode or OS specific steps may need to be tweaked to work on Linux.

The first thing you need to do is run the Vapor check to make sure that you have Swift installed correctly (for the most part, just install Xcode and you will be good to go). Run the check script:

eval "$(curl -sL check.vapor.sh)"

Hopefully, you should see a nice green tick and a message confirming you are good to go. Once you see this you can install the toolbox. On macOS the toolbox (and some other useful packages) are installed using Homebrew, which is a software dependency tool for macOS. Make sure you have installed Homebrew first.

Once Homebrew is installed, you need to add the Vapor tap, and then update your packages. You can then install the Vapor toolbox:

brew tap vapor/homebrew-tap
brew update
brew install vapor

If you run vapor --help you should hopefully see something similar to the following:

Vapor Toolbox Help

Creating a Project

All of the tutorials are going to be focused on building a reminders application using Vapor. So let's use the toolbox and start our project. To create a new project, run vapor new <Project-Name>. This will clone the default API template into a directory named after the project name. It will also set up the project with the correct names. So for us, we will run vapor new reminders:

Vapor New

If you go into the reminders directory, you will see all of the files needed for your starter project. So let's build the project; you can do this in two ways.

Building With Xcode

The first way, and most popular, is to use Xcode. If you run vapor xcode -y this will generate an Xcode project for your application and open it for you. Note that the first time you run this in your project, it will take some time as it needs to fetch all of the dependencies. Subsequent times will be much quicker!

Make sure you select the Run target for My Mac otherwise you will just build the module that holds your code, instead of the application:

Select Xcode Target

Then do CMD + R to build and run your application. After a while, you should see it build successfully and the macOS firewall may pop up asking for permission to allow the application to connect to the 8080 port - click 'Allow'. As with generating project, the first time you build the application can take some time, but subsequent builds will be much quicker.

Building With The Toolbox

You don't actually have to build your Vapor app with Xcode, you can do everything through the command line! This is useful for when running on Linux, or when you just want to build quickly to run some tests etc.

To build your application, simply run vapor build. Once you have built a binary, you then run vapor run to start the application (again, you may get a permission popup from the firewall - click 'Allow'):

Vapor Run CLI

Testing It Out

Once your Vapor app is running you can send some requests to it to make sure it is working! The API template sets up a number of routes by default so we can call these using curl. You can run curl http://localhost:8080/hello and you should get a JSON 'Hello, World!' response back, as well as some other routes:

Curl

(The -w "\n" is just there to print a new-line at the end of the response so it looks nice!) You can also visit these routes in your browser:

Browser

And that's it! You have successfully created your first Vapor app! Next time we will take a look at creating some reminders and how we save them.

All of the code for these tutorials can be found on Github, with this tutorial under the tutorial-1/getting-started tags.