This module provides the createApiAndServerDecs function. At compile time, it will read all the files under a specified directory, embed their contents, create a Servant "API" type synonym representing their directory layout, and create a ServerT function for serving their contents statically.

Let's assume that we have a directory called "dir" in the root of our Haskell web API that looks like this:

  $ tree dir/
  dir/
  ├── js
  │   └── test.js
  ├── hello.html
  └── index.html

Here's the contents of "hello.html", "index.html", and "js/test.js":

  $ cat dir/hello.html
  <p>Hello World</p>
  $ cat dir/index.html
  <p>This is the index</p>
  $ cat dir/js/test.js
  console.log("hello world");

The createApiAndServerDecs function can be used like the following:

  {-# LANGUAGE DataKinds #-}
  {-# LANGUAGE TemplateHaskell #-}

  import Data.Proxy (Proxy(Proxy))
  import Network.Wai (Application)
  import Network.Wai.Handler.Warp (run)
  import Servant.Server (serve)
  import Servant.Static.TH (createApiAndServerDecs)

  $(createApiAndServerDecs "FrontEndApi" "frontEndServer" "dir")

  app :: Application
  app = serve (Proxy :: Proxy FrontEndApi) frontEndServer

  main :: IO ()
  main = run 8080 app

createApiAndServerDecs will expand to something like the following at compile time:

  type FrontEndAPI =
    -- index.html is served on the root, as well as from the path "/index.html".
         Get '[HTML] Html
    :<|> "index.html" :> Get '[HTML] Html
    -- hello.html is served from the path "/hello.html".
    :<|> "hello.html" :> Get '[HTML] Html
    -- jstest.js is served from the path "js/test.js".
    :<|> "js" :> "test.js" :> Get '[JS] ByteString

  frontEndServer :: Applicative m => ServerT FrontEndAPI m
  frontEndServer =
         pure "<p>This is the index</p>"
    :<|> pure "<p>This is the index</p>"
    :<|> pure "<p>Hello World</p>"
    :<|> pure "console.log(\"hello world\");"

If this WAI application is running, it is possible to use curl to access the server:

  $ curl localhost:8080/
  <p>This is the index</p>
  $ curl localhost:8080/index.html
  <p>This is the index</p>
  $ curl localhost:8080/hello.html
  <p>Hello World</p>
  $ curl localhost:8080/js/test.js
  console.log("hello world");

This createApiAndServerDecs function is convenient to use when you want to make a Servant application easy to deploy. All the static frontend files are bundled into the Haskell binary at compile-time, so all you need to do is deploy the Haskell binary. This works well for low-traffic websites like prototypes and internal applications.

This shouldn't be used for high-traffic websites. Instead, you should serve your static files from something like Apache, nginx, or a CDN.

Note:

If you are creating a cabal package that needs to work with cabal-install, the "dir" you want to serve needs to be a relative path inside your project root, and all contained files need to be listed in your .cabal-file under the extra-source-files field so that they are included and available at compile-time.

The following types are the MIME types supported by servant-static-th. If you need additional MIME types supported, feel free to create an issue or PR.

The functions in this section pick defaults for the template directory, api name, and the server function name. This makes it easy to use for quick-and-dirty code.