Mustache Support

General Mustache support is provided by the finatra/mustache library.


The finatra/mustache library provides a mechanism to generate a String from a rendered Mustache template via the c.t.finatra.mustache.marshalling.MustacheService.

import com.twitter.finatra.mustache.marshalling.MustacheService

val mustacheService: MustacheService = injector.instance[MustacheService]
val result =
  mustacheService.createString("index.mustache", HtmlIndex("Bob", 45, Seq("Alice")))

The most common way to obtain the c.t.finatra.mustache.marshalling.MustacheService is from the injector.


To do so, you will need to include the c.t.finatra.mustache.modules.MustacheFactoryModule in the list of modules passed to create the injector. This module provides a correctly configured MustacheFactory which the c.t.finatra.mustache.marshalling.MustacheService uses. E.g.,

import com.twitter.finatra.mustache.modules.MustacheFactoryModule
import com.twitter.inject.server.TwitterServer

class MyServer extends TwitterServer {
    override val modules: Seq[Module] = Seq(MustacheFactoryModule)


Mustache templates are resolved by Finatra’s c.t.finatra.utils.FileResolver.

By default, files are loaded from the classpath root. To configure a classpath “namespace” for loading mustache templates, set the -mustache.templates.dir flag which is defined by the c.t.finatra.mustache.modules.MustacheFactoryModule.

Mustache templates are loaded from /templates by default.

The framework default “namespace” for Mustache templates is /templates, meaning the framework will try to resolve file file.mustache as /templates/file.mustache. To change this, set the -mustache.templates.dir flag to a different value. See: the Flag documentation here for information on setting flag values.

Local filesystem

When you set the -local.doc.root flag defined by the FlagResolverModule for configuring the c.t.finatra.utils.FileResolver, the c.t.finatra.mustache.modules.MustacheFactoryModule will load templates from the local filesystem and the templates will be reloaded on every render in order to aid in local development.

Note, that the interplay between the mustache.templates.dir and the local.doc.root flags is as follows:

  • in “local file mode” (e.g., when the -local.doc.root flag is set to a non-empty value) the framework will try to load a template first from the absolute path under mustache.templates.dir, e.g.,

  • if the template is not found, it will then be loaded from a location of mustache.templates.dir relative to the specified -local.doc.root, value e.g.,



It is not recommended that you set the -local.doc.root in a production environment, but rather load templates as classpath resources.

For more information on referencing files in Finatra, see the Working with Files section.