Static Files

Http4s can serve static files, subject to a configuration policy. There are three locations that Http4s can serve static content from: the filesystem, resources using the classloader, and WebJars.

All of these solutions are most likely slower than the equivalent in nginx or a similar static file hoster, but they're often fast enough.

Getting Started

To use fileService, the only configuration required is the relative path to the directory to serve. The service will automatically serve index.html if the request path is not a file. This service will also remove dot segments, to prevent attackers from reading files not contained in the directory being served.

import cats.effect._
import org.http4s.ember.server.EmberServerBuilder
import org.http4s.server.Server
import org.http4s.server.staticcontent._

object SimpleHttpServer extends IOApp {
  override def run(args: List[String]): IO[ExitCode] =
    app.use(_ => IO.never).as(ExitCode.Success)

  val app: Resource[IO, Server] =

Static content services can be composed into a larger application by using a Router:

val httpApp: HttpApp[IO] =
      "api"    -> anotherService,
      "assets" -> fileService(FileService.Config("./assets"))


Usually, if you fetch a file via HTTP, it ships with an ETag. An ETag specifies a file version. So the next time the browser requests that information, it sends the ETag along, and gets a 304 Not Modified back, so you don't have to send the data over the wire again.

Inline in a Route

For custom behaviour, StaticFile.fromPath can also be used directly in a route, to respond with a file:

import org.http4s._

val routes = HttpRoutes.of[IO] {
  case request @ GET -> Root / "index.html" =>
    StaticFile.fromPath(Path("relative/path/to/index.html"), Some(request))
      .getOrElseF(NotFound()) // In case the file doesn't exist

Serving from JARs

For simple file serving, it's possible to package resources with the jar and deliver them from there. For example, for all resources in the classpath under assets:

val assetsRoutes = resourceServiceBuilder[IO]("/assets").toRoutes

For custom behaviour, StaticFile.fromResource can be used. In this example, only files matching a list of extensions are served. Append to the List as needed.

def static(file: String, request: Request[IO]) =
  StaticFile.fromResource("/" + file, Some(request)).getOrElseF(NotFound())

val fileTypes = List(".js", ".css", ".map", ".html", ".webm")

val fileRoutes = HttpRoutes.of[IO] {
  case request @ GET -> Root / path if fileTypes.exists(path.endsWith) =>
    static(path, request)


A special service exists to load files from WebJars. Add your WebJar to the class path, as you usually would:

libraryDependencies ++= Seq(
  "org.webjars" % "jquery" % "3.1.1-1"

Then, mount the WebjarService like any other service:

import org.http4s.server.staticcontent.WebjarServiceBuilder.WebjarAsset
// only allow js assets
def isJsAsset(asset: WebjarAsset): Boolean =

val webjars: HttpRoutes[IO] = webjarServiceBuilder[IO]

Assuming that the service is mounted as root on port 8080, and you included the webjar swagger-ui-3.20.9.jar on your classpath, you would reach the assets with the path: http://localhost:8080/swagger-ui/3.20.9/index.html