Typesafe Activator

Contribute Template

Publish a Typesafe Activator Template

Template Developer Documentation

Create a New Template

Activator templates are just sbt projects with some metadata, a license, and a tutorial. When creating your own template either create an sbt project from scratch or start with an existing project. You can then open that project in the Activator UI to make sure it works as expected and to test the tutorial. Once you are ready to publish your template put it on GitHub and then use the form above to submit it to the template directory.

Update a Template

Once your changes have been pushed to your git repo, use the form above to publish a new version.

You may also configure a GitHub repository to auto-republish when you push. To add a Webhook to a GitHub repository go to the settings for the repository, select Webhooks & Services, then select Add webhook, and enter the following URL:
https://www.typesafe.com/activator/template/github-hook
The Payload version should be application/vnd.github.v3+form and the event is Just the push event. Save the new webhook and now every time you push to master in your repo the new template version will be automatically published.

Template Types

Activator displays two lists of templates, "Tutorials" and "Seeds." The seeds list contains all templates with the seed tag and the tutorials list contains all other templates.

Use the seed tag if your template is primarily intended as a starting point (boilerplate) for new applications. Don't use it if your template is primarily intended to teach about a technology.

Template Structure

There are four main parts to a template:

  • Metadata
  • License
  • sbt Build
  • Tutorial

These four pieces are combined into a project that can be used in Activator and as a regular sbt project. With Activator, when a user creates a new app from a template, the tutorial and the metadata are not included in the new project.

Metadata

Activator templates must provide an activator.properties file which contains the template metadata. The required properties are:

  • name - A globally unique, URL friendly name for the template (don't put "template" or "activator" in it please).
  • title - A human readable name for the template.
  • description - A plain text description for the template.
  • tags - A comma-separated list of tags for the template.

These values will be verified when you publish your template.

Example activator.properties:

name=play-with-angular
title=Play Framework with AngularJS
description=A starter application with Play Framework and AngularJS.
tags=playframework,angularjs,java,scala

The following fields are automatically filled in if you publish from GitHub, but you can put them in activator.properties to override:

  • authorName - Author name; autofilled with GitHub username. Can be a company name or person's name.
  • authorLink - Link to author's website; autofilled with GitHub user page.
  • sourceLink - Link to template's source; autofilled with GitHub project link.

The following fields are optional and not autofilled with anything:

  • authorLogo - URL for a logo; must be an http, https, or data URI. Must be a JPEG, PNG, or GIF. Should be either 100x70 pixels or 200x140 pixels (200x140 is for retina support). We will download your URL at publish time and host the logo on our server.
  • authorBio - Plain text bio for the author. No HTML tags.
  • authorTwitter - Twitter username for the author.

License

Activator templates must have a license which permits others to build an app based on the template. This template must be in a file that has a name beginning with LICENSE and can be in plain text or Markdown. Markdown licenses should be named LICENSE.md. Generally seed templates should use a very liberal license like CC0 while sample applications can use something slightly more restrictive like Apache 2. Inclusion of copyright headers is up to the author.

sbt Build

The project must set a required sbt version in the project/build.properties file, like:

sbt.version=0.12.4

Projects can use the legacy Maven layout (which is the default for plain sbt projects) or Play Framework's layout.

Tutorial

The tutorial for a template is in a tutorial/index.html file. Each section of the tutorial must be in a <div> tag that is inside the <body> tag. Each section must have a single <h2> tag that contains the section's title. The tutorial can provide shortcut links to places in Activator by using an anchor link (#) and the shortcut class, like:

<a href="#code/tutorial/index.html" class="shortcut">/tutorial/index.html</a>

Code blocks can use <pre><code></code></pre> tags, like:

<pre><code>println("hello, Scala!")
        val foo = "Bar"</code></pre>

In-line code can use just the <code></code> tag, like:

The <code>val foo = "Bar"</code> statement sets <code>foo</code> to <code>Bar</code>

Images can be embedded by putting them in the tutorial directory and using a relative URL to the image, like:

<img src="tutorial/tutorial.png">

Questions or Problems?

Search and create issues on GitHub