This is the start of a series of tutorials on Vapor. For more, click here
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?
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:
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:
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:
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'):
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:
-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:
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.