# Getting Started - Vapor Docs

Skip to content


# Leaf

Leaf is a powerful templating language with Swift-inspired syntax. You can use it to generate dynamic HTML pages for a front-end website or generate rich emails to send from an API.

## Package

The first step to using Leaf is adding it as a dependency to your project in your SPM package manifest file.

    // swift-tools-version:4.0
    import PackageDescription

    let package = Package(
        name: "MyApp",
        dependencies: [
            /// Any other dependencies ...
            .package(url: "https://github.com/vapor/leaf.git", from: "3.0.0"),
        ],
        targets: [
            .target(name: "App", dependencies: ["Leaf", ...]),
            .target(name: "Run", dependencies: ["App"]),
            .testTarget(name: "AppTests", dependencies: ["App"]),
        ]
    )

## Configure

Once you have added the package to your project, you can configure Vapor to use it. This is usually done in `configure.swift`.

    import Leaf

    try services.register(LeafProvider())

If your application supports multiple view renderers, you may need to specify that you would like to use Leaf.

    config.prefer(LeafRenderer.self, for: ViewRenderer.self)

## Folder Structure

Once you have configured Leaf, you will need to ensure you have a `Views` folder to store your `.leaf` files in. By default, Leaf expects the views folder to be a `./Resources/Views` relative to your project's root.

You will also likely want to enable Vapor's `FileMiddleware` to serve files from your `/Public` folder.

    VaporApp
    ├── Package.swift
    ├── Resources
    │   ├── Views
    │   │   └── hello.leaf
    ├── Public
    │   ├── images (images resources)
    │   ├── styles (css resources)
    └── Sources
        └── ...

## Syntax Highlighting

You may also wish to install one of these third-party packages that provide support for syntax highlighting in Leaf templates.

### Sublime

Install the package Leaf from package control.

### Atom

language-leaf by ButkiewiczP

### Xcode

It is currently not possible to implement Leaf Syntax Highlighting in Xcode, however, using Xcode's HTML Syntax Coloring can help a bit. Select one or more Leaf files and then choose Editor > Syntax Coloring > HTML. Your selected Leaf files will now use Xcode's HTML Syntax Coloring. Unfortunately the usefulness of this is limited because this association will be removed when `vapor xcode` is run.

There appears to be a way to make Xcode file associations persist but that requires a bit more kung-fu.

Also, there is a unsupported solution that associates `.leaf`-files in Xcode with HTML syntax coloring automatically: xcode-leaf-color-schemer by ashokgelal.

### VS Code

html-leaf by FranciscoAmado

### CLion & AppCode

Some preliminary work has been done to implement a Leaf Plugin for CLion & AppCode but lack of skill and interest in Java has slowed progress! If you have IntelliJ SDK experience and want to help with this, message Tom Holland on Vapor Slack

## Rendering a View

Now that Leaf is configured, let's render your first template. Inside of the `Resources/Views` folder, create a new file called `hello.leaf` with the following contents:

    Hello, #(name)!

Then, register a route (usually done in `routes.swift` or a controller) to render the view.

    import Leaf

    router.get("hello") { req -> Future<View> in
        return try req.view().render("hello", ["name": "Leaf"])
    }

Open your browser and visit `/hello`. You should see `Hello, Leaf!`. Congratulations on rendering your first Leaf view!

## Comments