Introduction to Vapor 3 -- Hello World


What is Vapor?

  • Vapor is a server side framework, written in Swift. Swift is a programming language released by Apple in 2014, and is now used widely to write apps for the iPhone, iPad, and the Mac. You can use Vapor to create database backed-web apps, backend APIs for mobile apps, and chat applications.
  • It works on MacOS and Ubuntu
  • It uses the Swift Package Manager to manage dependencies

Requirements in order to complete this tutorial:

  • Mac OS High Sierra
  • Xcode 9.3 - Beta 2 or later

If you do not have at least Xcode 9.3, you cannot run Vapor 3, as Vapor 3 requires Swift 4.1, which is only available on Xcode 9.3.

What's New in Vapor 3

The short, sweet version is:
  • Async: Vapor 3 routing is async by default. This will change how we write our route handlers, but makes Vapor 3 blazing fast
  • Codable: Swift 4's Codable is used everywhere: in database interactions, queries, decoding/encoding network requests, and more
  • No more JSON configuration. All configuration is done in Swift
  • Key Path support: Vapor 3 uses Swift 4's Key Path support to help reduce run time errors, by catching them at run time.

There is a much more detailed and comprehensive article about the differences, here

Getting Started

Step 1: Install Homebrew (if you already have Homebrew installed, you can skip this step).

First, let's install Homebrew. Simply run the following command in terminal:

Note: If you already have Vapor 2 (or Vapor 3 beta) installed on your machine, simply run $ brew vapor update, and you can skip the steps below.

    $ /usr/bin/ruby -e "$(curl -fsSL"
Step 2: Add Homebrew Tap Next, we need to give Homebrew access to Vapors MacOS packages. To do so, simply run:
    $ brew tap vapor/homebrew-tap

And then:

    $ brew update
Step 3: Installing Vapor. Run the following command:
    $ brew install vapor

After installation is complete, you can test to make sure everything is installed correctly. Run:

    $ vapor --version

And the output should say:

    Vapor Toolbox: 3.1.7
    Vapor Framework: 3.0.0

Great! Vapor is now installed, and we are ready to create our first project.

Vapor commands

Before we proceed, run the following in terminal:

    $ vapor --help 

You should see the following come up:

Here we see a list of commands that we can use with Vapor's CLI (command line interface).

We won't be using all of these, but to start, I'll just point out a few of the common ones that you will need to use on a regular basis:

  • vapor new: this command is how we create a new project (which we'll do in a second). New project names should be CamelCase (e.g., vapor new MyProject)
  • vapor update: When you add a new dependency to your project, you will always have to do 2 things: 1) run vapor update and 2) run vapor Xcode to regenerate the Xcode project.
  • vapor xcode: As stated above, this generates an Xcode project for you. It must be run after adding dependencies to your Package.swift file.
  • vapor clean: Cleans your build folder. If you are getting a random error, try running this and see if it helps.
  • vapor build: Builds the application. However, we will be doing this using Xcode instead.

Creating a Project

Time to create your first Vapor project! In terminal, run:

    $ vapor new HelloWorld

This may take a few moments. Upon completion, you should see:

Great! As it says, now run $ cd HelloWorld to enter into our project directory.

Once in your project directory, we need to generate an Xcode Project. Run:

    $ vapor xcode

This may take a few moments as well. Upon completion, you will see:

    Generating Xcode Project [Done]
    Select the Run scheme to run.
    Open Xcode project?

Respond with `y` to open it, and then press Enter. When opening the project, you should see this:

To run our project, we must change one thing. Click where it says "HelloWorld-Package" at the top:

And scroll down to where it says "Run", and select that:

It should now look like:

Now run the project by clicking the Play button at the top left, and navigate to http://localhost:8080/hello. You should see:

Hello, World!

And that's your first Vapor project! There is much, much more to learn with Vapor as well. There will be plenty of tutorials to come in the near future.

Thanks for reading!