First steps

Generate a Scalatra project

Now that installation is out of the way, you can generate a project:

$ sbt new scalatra/scalatra.g8

This will check out a pre-built application skeleton for you (from GitHub), and ask you some questions about your application:

$ sbt new scalatra/scalatra.g8
organization [com.example]:
name [My Scalatra Web App]:
version [0.1.0-SNAPSHOT]:
servlet_name [MyScalatraServlet]:
package [com.example.app]:
scala_version [2.13.12]:
sbt_version [1.9.7]:
scalatra_version [3.0.0]:

Template applied in ./my-scalatra-web-app

organization

Used for publishing. Should be the reverse of a domain name you control. If you don't own a domain, io.github.username is a popular choice.

package

All Scala code belongs in a package. The Scala Style Guide recommends that your packages start with your organization. This convention is used across multiple JVM languages and gives your project a globally unique namespace.

name

The name of your project. g8 will generate a project into a folder of that name, and the artifacts you publish will be based on that name.

version

Your project's version. This is entirely up to you, but we like semantic versioning.

servlet_name

The name of your servlet class. This might be something like BlogServlet or just Blog.

scala_version

The Scala version to use. The bottom of the homepage lists which Scala versions are compatible with the latest Scalatra releases. When in doubt, use the default.

sbt_version

The sbt version.

scalatra_version

The Scalatra version to use. See the homepage for a list. You can choose a stable version or if you want to try out new features go with a RC or SNAPSHOT.

Building

Scala is a compiled language, so you need to build your Scalatra project.

Enter your application’s top-level directory, just execute sbt to start building your Scalatra project.

For example:

$ cd /your/project/directory
$ sbt

sbt will also take care of downloading an entire Scalatra development environment if you don’t have one yet. That means sbt may spend some time downloading Scalatra and its libraries on first run.

Hello world

Now that Scalatra is installed, how about making your first application? Source files go into src/main/scala/com/example/app (substitute your package for com/example/app). Open src/main/scala/com/example/app/MyScalatraServlet.scala, or whatever you named your servlet when you generated your project with Scalatra template:

package com.example.app

import org.scalatra._

class MyScalatraServlet extends ScalatraServlet {

  get("/") {
    views.html.hello()
  }

}

If you haven’t already done so, from your project root, you can run the project:

$ sbt
> Jetty/start

The application starts on http://localhost:8080.

Scalatra allows you to return strongly-typed results from any of its actions. The action above returns an XML literal - you could easily change it to return a string by altering the action:

get("/") {
  "Hi there!"
}

Returning a raw string is not something you’ll do particularly often - usually you will want to return formatted HTML that is the product of a templating system, or an output format like JSON. See the views section of our guides for more info.

Automatic code reloading

Restarting an application manually after every code change is both slow and painful. It can easily be avoided by using a tool for automatic code reloading.

sbt will allow you to signal a restart of the application when it detects code changes. The syntax for restarting involves adding ~ in front of the command you want to re-execute. To recompile and reload your application automatically, run the following:

$ sbt
> ~Jetty/start

Now that you’ve got a (rather simplistic) running application, you may want to understand more about the project setup, or dive straight into our guides, which show you how to perform common development tasks.

Many of the Scalatra guides have companion code projects, so you can learn by seeing running example code in action.