Servant.Static.TH

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

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

  $ cat dir/index.html
  <p>Hello World</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 =
         "js" :> "test.js" :> Get '[JS] ByteString
    :<|> "index.html" :> Get '[HTML] Html

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

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

  $ 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.

Create API

createApiType

Arguments

:: FilePath

directory name to read files from

-> Q Type

Take a template directory argument as a FilePath and create a Servant type representing the files in the directory. Empty directories will be ignored.

For example, assume the following directory structure:

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

createApiType is used like the following:

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

  type FrontEndAPI = $(createApiType "dir")

At compile time, it will expand to the following:

  type FrontEndAPI =
         "js" :> "test.js" :> Get '[JS] ByteString
    :<|> "index.html" :> Get '[HTML] Html

createApiDec

Arguments

:: String

name of the api type synonym

-> FilePath

directory name to read files from

-> Q [Dec]

This is similar to createApiType, but it creates the whole type synonym declaration.

Given the following code:

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

  $(createApiDec "FrontAPI" "dir")

You can think of it as expanding to the following:

  type FrontAPI = $(createApiType "dir")

Create Server

createServerExp :: FilePath -> Q Exp

Take a template directory argument as a FilePath and create a ServerT function that serves the files under the directory. Empty directories will be ignored.

Note that the file contents will be embedded in the function. They will not be served dynamically at runtime. This makes it easy to create a Haskell binary for a website with all static files completely baked-in.

For example, assume the following directory structure and file contents:

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

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

createServerExp is used like the following:

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

  type FrontEndAPI = $(createApiType "dir")

  frontEndServer :: Applicative m => ServerT FrontEndAPI m
  frontEndServer = $(createServerExp "dir")

At compile time, this expands to something like the following. This has been slightly simplified to make it easier to understand:

  type FrontEndAPI =
         "js" :> "test.js" :> Get '[JS] ByteString
    :<|> "index.html" :> Get '[HTML] Html

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

createServerDec

Arguments

:: String

name of the api type synonym

-> String

name of the server function

-> FilePath

directory name to read files from

-> Q [Dec]

This is similar to createServerExp, but it creates the whole function declaration.

Given the following code:

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

  $(createServerDec "FrontAPI" "frontServer" "dir")

You can think of it as expanding to the following:

  frontServer :: Applicative m => ServerT FrontAPI m
  frontServer = $(createServerExp "dir")

Create Both API and Server

createApiAndServerDecs

Arguments

:: String

name of the api type synonym

-> String

name of the server function

-> FilePath

directory name to read files from

-> Q [Dec]

This is a combination of createApiDec and createServerDec. This function is the one most users should use.

Given the following code:

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

  $(createApiAndServerDecs "FrontAPI" "frontServer" "dir")

You can think of it as expanding to the following:

  $(createApiDec "FrontAPI" "dir")

  $(createServerDec "FrontAPI" "frontServer" "dir")

MIME Types

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.

data CSS

Instances

Accept CSS

text/css

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy CSS -> MediaType

contentTypes :: Proxy CSS -> NonEmpty MediaType

MimeRender CSS ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy CSS -> ByteString -> ByteString0

data EOT

Since: 0.2.0.0

Instances

Accept EOT

fonts/eot

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy EOT -> MediaType

contentTypes :: Proxy EOT -> NonEmpty MediaType

MimeRender EOT ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy EOT -> ByteString -> ByteString0

data GEXF

GEXF file (xml for graph application)

Instances

Accept GEXF

application/gexf

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy GEXF -> MediaType

contentTypes :: Proxy GEXF -> NonEmpty MediaType

MimeRender GEXF ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy GEXF -> ByteString -> ByteString0

data GIF

Instances

Accept GIF

image/gif

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy GIF -> MediaType

contentTypes :: Proxy GIF -> NonEmpty MediaType

MimeRender GIF ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy GIF -> ByteString -> ByteString0

data HTML

Instances

Accept HTML

text/html;charset=utf-8

Defined in Servant.HTML.Blaze

Methods

contentType :: Proxy HTML -> MediaType

contentTypes :: Proxy HTML -> NonEmpty MediaType

ToMarkup a => MimeRender HTML a

Defined in Servant.HTML.Blaze

Methods

mimeRender :: Proxy HTML -> a -> ByteString

type Html = Markup

data ICO

Since: 0.2.0.0

Instances

Accept ICO

icon/ico

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy ICO -> MediaType

contentTypes :: Proxy ICO -> NonEmpty MediaType

MimeRender ICO ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy ICO -> ByteString -> ByteString0

data JPEG

Instances

Accept JPEG

image/jpeg

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy JPEG -> MediaType

contentTypes :: Proxy JPEG -> NonEmpty MediaType

MimeRender JPEG ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy JPEG -> ByteString -> ByteString0

data JS

Instances

Accept JS

application/javascript

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy JS -> MediaType

contentTypes :: Proxy JS -> NonEmpty MediaType

MimeRender JS ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy JS -> ByteString -> ByteString0

data JSON

JSON file

Instances

Accept JSON

application/json

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy JSON -> MediaType

contentTypes :: Proxy JSON -> NonEmpty MediaType

MimeRender JSON ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy JSON -> ByteString -> ByteString0

data PNG

Instances

Accept PNG

image/png

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy PNG -> MediaType

contentTypes :: Proxy PNG -> NonEmpty MediaType

MimeRender PNG ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy PNG -> ByteString -> ByteString0

data SVG

Instances

Accept SVG

image/svg

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy SVG -> MediaType

contentTypes :: Proxy SVG -> NonEmpty MediaType

MimeRender SVG ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy SVG -> ByteString -> ByteString0

data TTF

Since: 0.2.0.0

Instances

Accept TTF

fonts/ttf

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy TTF -> MediaType

contentTypes :: Proxy TTF -> NonEmpty MediaType

MimeRender TTF ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy TTF -> ByteString -> ByteString0

data TXT

Instances

Accept TXT

text/plain

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy TXT -> MediaType

contentTypes :: Proxy TXT -> NonEmpty MediaType

MimeRender TXT ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy TXT -> ByteString -> ByteString0

data WOFF

Since: 0.2.0.0

Instances

Accept WOFF

fonts/woff

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy WOFF -> MediaType

contentTypes :: Proxy WOFF -> NonEmpty MediaType

MimeRender WOFF ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy WOFF -> ByteString -> ByteString0

data WOFF2

Since: 0.2.0.0

Instances

Accept WOFF2

fonts/woff2

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy WOFF2 -> MediaType

contentTypes :: Proxy WOFF2 -> NonEmpty MediaType

MimeRender WOFF2 ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy WOFF2 -> ByteString -> ByteString0

data XML

XML file

Instances

Accept XML

application/xml

Defined in Servant.Static.TH.Internal.Mime

Methods

contentType :: Proxy XML -> MediaType

contentTypes :: Proxy XML -> NonEmpty MediaType

MimeRender XML ByteString

Defined in Servant.Static.TH.Internal.Mime

Methods

mimeRender :: Proxy XML -> ByteString -> ByteString0

Easy-To-Use Names and Paths

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.

Paths and Names

frontEndTemplateDir :: FilePath

This is the directory "frontend/dist".

frontEndApiName :: String

This is the String "FrontEnd".

frontEndServerName :: String

This is the String "frontEndServer".

API

createApiFrontEndType :: Q Type

This is the same as createApiType frontEndTemplateDir.

createApiFrontEndDec :: Q [Dec]

This is the same as createApiDec frontEndApiName frontEndTemplateDir.

Server

createServerFrontEndExp :: Q Exp

This is the same as createServerExp frontEndTemplateDir.

createServerFrontEndDec :: Q [Dec]

This is the same as createServerDec frontEndApiName frontEndServerName frontEndTemplateDir.

Server and API

createApiAndServerFrontEndDecs :: Q [Dec]

This is the same as createApiAndServerDecs frontEndApiName frontEndServerName frontEndTemplateDir.