Create fully interactive HTML applications with type-safe serverside Haskell. Inspired by HTMX, Elm, and Phoenix LiveView

Single Page Applications (SPAs) require the programmer to write two programs: a Javascript client and a Server, which both must conform to a common API

Hyperbole allows us to instead write a single Haskell program which runs exclusively on the server. All user interactions are sent to the server for processing, and a sub-section of the page is updated with the resulting HTML.

There are frameworks that support this in different ways, including HTMX, Phoenix LiveView, and others. Hyperbole has the following advantages

1. 100% Haskell
2. Type safe views, actions, routes, and forms
3. Elegant interface with little boilerplate
4. VirtualDOM updates over sockets, fallback to HTTP
5. Easy to use

Like HTMX, Hyperbole extends the capability of UI elements, but it uses Haskell's type-system to prevent common errors and provide default functionality. Specifically, a page has multiple update targets called HyperViews. These are automatically targeted by any UI element that triggers an action inside them. The compiler makes sure that actions and targets match

Like Phoenix LiveView, it upgrades the page to a fast WebSocket connection and uses VirtualDOM for live updates

Like Elm, it uses an update function to process actions, but greatly simplifies the Elm Architecture by remaining stateless. Effects are handled by Effectful. forms are easy to use with minimal boilerplate

Hyperbole depends heavily on the following frameworks

• Effectful
• Web View

Hyperbole applications run via Warp and WAI

They are divided into top-level Pages, which can run side effects (like loading data), then respond with an HTML View. The following application has a single Page that displays a static "Hello World"

{-# LANGUAGE DeriveAnyClass #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE TypeFamilies #-}
{-# LANGUAGE DataKinds #-}

module Main where

import Web.Hyperbole

main = do
  run 3000 $ do
    liveApp (basicDocument "Example") (runPage messagePage)

messagePage :: Eff es (Page '[])
messagePage = do
  pure $ do
    col (pad 10) $ do
      el bold "Hello World"

We can include one or more HyperViews to add type-safe interactivity to live subsections of the Page. To start, first define a data type (a ViewId) that uniquely identifies that subsection of the page:

data Message = Message
  deriving (Show, Read, ViewId)

Make our ViewId an instance of HyperView by:

• Create an Action type with a constructor for every possible way that the user can interact with it
• Write an update for each Action

instance HyperView Message es where
  data Action Message
    = SetMessage Text
    deriving (Show, Read, ViewAction)

  update (SetMessage t) =
    pure $ el bold (text t)

Replace the static message with our new HyperView using hyper, and add our ViewId to the Page type signature. Then add a button to trigger the Action:

messagePage :: Eff es (Page '[Message])
messagePage = do
  pure $ do
    col (pad 10 . gap 10) $ do
      hyper Message $ do
        el bold "Hello World"
        button (SetMessage "Goodbye") (border 1) "Say Goodbye"

The contents of hyper will be replaced with the result of update, leaving the rest of the page untouched.

Rather than showing a completely different HTML View on each update, we can create a View Function for our HyperView. These are pure functions with state parameters, which return a View. The compiler will tell us if we try to trigger an Action for a HyperView that doesn't match our View context

Each HyperView should have a main view function that renders it based on its state:

messageView :: Text -> View Message ()
messageView m = do
  el bold $ text $ "Message: " <> m
  button (SetMessage "Goodbye") (border 1) "Say Goodbye"

Now we can refactor to use the same view function for both the initial hyper and the update. The only thing that will change on an update is the text of the message.

messagePage :: Eff es (Page '[Message])
messagePage = do
  pure $ do
    hyper Message $ messageView "Hello"

instance HyperView Message es where
  data Action Message
    = SetMessage Text
    deriving (Show, Read, ViewAction)

  update (SetMessage t) =
    pure $ messageView t

We can create multiple view functions with our HyperView as the context, and factor them however is most convenient.

goodbyeButton :: View Message ()
goodbyeButton = do
  button (SetMessage "Goodbye") (border 1) "Say Goodbye"

We can also create view functions that work in any context.

header :: Text -> View c ()
header txt = do
  el bold (text txt)

Factored this way, our main View for Message becomes:

messageView' :: Text -> View Message ()
messageView' m = do
  header $ "Message: " <> m
  goodbyeButton

HyperViews are stateless. They update based entirely on the Action. However, we can track simple state by passing it back and forth between the Action and the View

From Example.Page.Simple

instance HyperView Message es where
  data Action Message
    = Louder Text
    deriving (Show, Read, ViewAction)

  update (Louder m) = do
    let new = m <> "!"
    pure $ messageView new

messageView :: Text -> View Message ()
messageView m = do
  button (Louder m) (border 1) "Louder"
  el bold $ text $ "Message: " <> m

For any real application with more complex state and data persistence, we need side effects.

Hyperbole relies on Effectful to compose side effects. We can use effects in a Page or an update. In this example, each client stores the latest message in their session.

From Example.Page.Simple

messagePage :: (Hyperbole :> es) => Eff es (Page '[Message])
messagePage = do
  stored <- session @Text "message"
  let msg = fromMaybe "Hello" stored
  pure $ do
    hyper Message $ messageView msg

instance HyperView Message es where
  data Action Message
    = Louder Text
    deriving (Show, Read, ViewAction)

  update (Louder m) = do
    let new = m <> "!"
    setSession "message" new
    pure $ messageView new

To use an Effect other than Hyperbole, add it as a constraint to the Page and any HyperView instances that need it. Then run the effect in your application

From Example.Page.Counter

{-# LANGUAGE UndecidableInstances #-}

instance (Reader (TVar Int) :> es, Concurrent :> es) => HyperView Counter es where
  data Action Counter
    = Increment
    | Decrement
    deriving (Show, Read, ViewAction)

  update Increment = do
    n <- modify (+ 1)
    pure $ viewCount n
  update Decrement = do
    n <- modify (subtract 1)
    pure $ viewCount n

A database is no different from any other Effect. We recommend you create a custom effect to describe high-level data operations.

From Example.Effects.Todos

data Todos :: Effect where
  LoadAll :: Todos m [Todo]
  Save :: Todo -> Todos m ()
  Remove :: TodoId -> Todos m ()
  Create :: Text -> Todos m TodoId

loadAll :: (Todos :> es) => Eff es [Todo]
loadAll = send LoadAll

Once you've created an Effect, you add it to any HyperView or Page as a constraint.

From Example.Page.Todo:

{-# LANGUAGE UndecidableInstances #-}

simplePage :: (Todos :> es) => Eff es (Page '[AllTodos, TodoView])
simplePage = do
  todos <- Todos.loadAll
  pure $ do
    hyper AllTodos $ todosView FilterAll todos

When you create your Application, run any Effects you need. Here we are using a runner that implements the effect with sessions from Hyperbole, but you could write a different runner that connects to a database instead.

From example/Main.hs:

app :: Application
app = do
  liveApp
    toDocument
    (runApp . routeRequest $ router)
 where
  runApp :: (Hyperbole :> es, IOE :> es) => Eff (Concurrent : Todos : es) a -> Eff es a
  runApp = runTodosSession . runConcurrent

Implementing a database runner for a custom Effect is beyond the scope of this documentation, but see the following:

• Effectful.Dynamic.Dispatch - Introduction to Effects
• NSO.Data.Datasets - Production Data Effect with a database runner
• Effectful.Rel8 - Effect for the Rel8 Postgres Library

We can add as many HyperViews to a page as we want. Let's create another HyperView for a simple counter

From Example.Intro.MultiView

data Count = Count
  deriving (Show, Read, ViewId)


instance HyperView Count es where
  data Action Count
    = Increment Int
    | Decrement Int
    deriving (Show, Read, ViewAction)

  update (Increment n) = do
    pure $ countView (n + 1)
  update (Decrement n) = do
    pure $ countView (n - 1)


countView :: Int -> View Count ()
countView n = do
  el_ $ text $ pack $ show n
  button (Increment n) (border 1) "Increment"
  button (Decrement n) (border 1) "Decrement"

We can use both Message and Count HyperViews in our page, and they will update independently:

page :: Eff es (Page '[Message, Count])
page = do
  pure $ do
    row id $ do
      hyper Message $ messageView "Hello"
      hyper Count $ countView 0

We can embed multiple copies of the same HyperView as long as the value of ViewId is unique. Let's update Message to allow for more than one value:

See Example.Page.Simple

data Message = Message1 | Message2
  deriving (Show, Read, ViewId)

Now we can embed multiple Message HyperViews into the same page. Each will update independently.

messagePage :: Eff es (Page '[Message])
messagePage = do
  pure $ do
    hyper Message1 $ messageView "Hello"
    hyper Message2 $ messageView "World!"

This is especially useful if we put identifying information in our ViewId, such as a database id. The Contacts Example uses this to allow the user to edit multiple contacts on the same page. The viewId function gives us access to that info

From Example.Contacts

data Contact = Contact UserId
  deriving (Show, Read, ViewId)

instance (Users :> es, Debug :> es) => HyperView Contact es where
  data Action Contact
    = Edit
    | Save
    | View
    deriving (Show, Read, ViewAction)

  update action = do
    -- No matter which action we are performing, let's look up the user to make sure it exists
    Contact uid <- viewId
    u <- Users.find uid
    case action of
      View -> do
        pure $ contactView u
      Edit -> do
        pure $ contactEdit u
      Save -> do
        delay 1000
        unew <- parseUser uid
        Users.save unew
        pure $ contactView unew

We can nest smaller, specific HyperViews inside of a larger parent. You might need this technique to display a list of items which need to update themselves

Let's imagine we want to display a list of Todos. The user can mark individual todos complete, and have them update independently. The specific HyperView might look like this:

From Example.Intro.Nested

data TodoItem = TodoItem
  deriving (Show, Read, ViewId)

instance HyperView TodoItem es where
  data Action TodoItem
    = Complete Todo
    deriving (Show, Read, ViewAction)

  update (Complete todo) = do
    let new = todo{completed = True}
    pure $ todoView new

But we also want the entire list to refresh when a user adds a new todo. We need to create a parent HyperView for the whole list.

List all allowed nested views by adding them to Require

data AllTodos = AllTodos
  deriving (Show, Read, ViewId)

instance HyperView AllTodos es where
  type Require AllTodos = '[TodoItem]

  data Action AllTodos
    = AddTodo Text [Todo]
    deriving (Show, Read, ViewAction)

  update (AddTodo txt todos) = do
    let new = Todo txt False : todos
    pure $ todosView new

Then we can embed the child HyperView into the parent with hyper

todosView :: [Todo] -> View AllTodos ()
todosView todos = do
  forM_ todos $ todo -> do
    hyper TodoItem $ todoView todo
  button (AddTodo "Shopping" todos) id "Add Shopping"

See this technique used in the TodoMVC Example

You may be tempted to use HyperViews to create reusable Components. This leads to object-oriented designs that don't compose well. We are using a functional language, so our main unit of reuse should be functions!

We showed earlier that we can write a View Function with a generic context that we can reuse in any view. A function like this might help us reuse styles:

header :: Text -> View c ()
header txt = do
  el bold (text txt)

What if we want to reuse functionality too? We can pass an Action into the view function as a parameter:

styledButton :: (ViewAction (Action id)) => Action id -> Text -> View id ()
styledButton clickAction lbl = do
  button clickAction (pad 10 . bg Primary . hover (bg PrimaryLight) . rounded 5) (text lbl)

We can create more complex view functions by passing state in as a parameter. Here's a button that toggles between a checked and unchecked state:

toggleCheckBtn :: (ViewAction (Action id)) => Action id -> Bool -> View id ()
toggleCheckBtn clickAction isSelected = do
  button clickAction (width 32 . height 32 . border 1 . rounded 100) contents
 where
  contents = if isSelected then Icon.check else " "

Don't leverage HyperViews for code reuse. Think about which subsections of a page ought to update independently. Those are HyperViews. If you need reusable functionality, use view functions instead.

• See Example.View.DataTable for a more complex example

An app has multiple Pages with different Routes that each map to a unique url path:

data AppRoute
  = Message -- /message
  | Counter -- /counter
  deriving (Generic, Eq, Route)

When we define our app, we define a function that maps a Route to a Page

main = do
  run 3000 $ do
    liveApp (basicDocument "Multiple Pages") (routeRequest router)
 where
  router Message = runPage Message.page
  router Counter = runPage Counter.page

Each Page is completely independent. The web page is freshly reloaded each time you switch routes. We can add type-safe links to other pages using route

menu :: View c ()
menu = do
  route Message id "Link to /message"
  route Counter id "Link to /counter"

If you need the same header or menu on all pages, use a view function:

exampleLayout :: View c () -> View c ()
exampleLayout content = do
  layout id $ do
    el (border 1) "My Website Header"
    row id $ do
      menu
      content

examplePage :: Eff es (Page '[])
examplePage = do
  pure $ exampleLayout $ do
    el_ "page contents"

As shown above, each Page can contain multiple interactive HyperViews to add interactivity

https://docs.hyperbole.live is full of live examples demonstrating different features. Each example includes a link to the source code. Some highlights:

• Simple
• Counter
• CSS Transitions
• Lazy Loading
• Forms
• Data Table
• Filter Items
• Autocomplete
• Todo MVC

The National Solar Observatory uses Hyperbole for the Level 2 Data creation tool for the DKIST telescope. It is completely open source. This production application contains complex interfaces, workers, databases, and more.

Painless forms with type-checked field names, and support for validation. See Example.Forms

Hyperbole is tightly integrated with Web.View for HTML generation