servant-typescript: TypeScript client generation for Servant

[ bsd3, library, program, web ] [ Propose Tags ]


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


  • No Candidates
Versions [RSS],,
Change log
Dependencies aeson, aeson-typescript, base (>=4.7 && <5), containers, directory, filepath, lens, mtl, servant, servant-foreign, servant-typescript, string-interpolate, text [details]
License BSD-3-Clause
Copyright 2022 Tom McLaughlin
Author Tom McLaughlin
Category Web
Home page
Bug tracker
Source repo head: git clone
Uploaded by thomasjm at 2022-03-20T03:44:15Z
Executables servant-typescript-exe
Downloads 207 total (6 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2022-03-20 [all 1 reports]

Readme for servant-typescript-

[back to package description]

Welcome to servant-typescript Hackage servant-typescript

This library generates TypeScript client libraries for Servant.

First, make sure you have TypeScript instances defined for all of the types used in the API.

data User = User {
  name :: String
  , age :: Int
  , email :: String
  } deriving (Eq, Show)
deriveJSONAndTypeScript A.defaultOptions ''User

If you need to generate lots of boilerplate instances, the functions in aeson-typescript's Recursive module can be your friend. I've used recursivelyDeriveMissingTypeScriptInstancesFor to derive instances for the Kubernetes API.

Next, you'll need some Servant API:

type UserAPI = "users" :> Get '[JSON] [User]
          :<|> "albert" :> Get '[JSON] User
          :<|> "isaac" :> Get '[JSON] User

Generating the library is as simple as this:

main = writeTypeScriptLibrary (Proxy :: Proxy UserAPI) "/my/destination/folder/"


  • This library doesn't yet support generating generic TypeScript functions to match generic TypeScript instances. You can hack around this by writing your own getFunctions and hardcoding them manually for the necessary types.

Supporting additional combinators

If you use unusual Servant combinators in your API, you may need to define additional HasForeign instances to explain how to convert them to TypeScript. For example, when I work with the servant-websockets package, I add instances like the following.

The same applies to custom AuthProtect combinators from Servant.API.Experimental.Auth, etc.

instance HasForeign LangTS Text WebSocket where
    type Foreign Text WebSocket = Text
    foreignFor _ _ _ _ = "void"

instance HasForeign LangTSDecls [TSDeclaration] WebSocket where
    type Foreign [TSDeclaration] WebSocket = [TSDeclaration]
    foreignFor _ _ _ _ = []