Ports

Ports allow communication between Elm and JavaScript.

Ports are probably most commonly used for WebSockets and localStorage. Let’s focus on the WebSockets example.

Ports in JavaScript

Here we have pretty much the same HTML we have been using on the previous pages, but with a bit of extra JavaScript code in there. We create a connection to wss://echo.websocket.org that just repeats back whatever you send it. You can see in the live example that this lets us make the skeleton of a chat room:

  1. <!DOCTYPE HTML>
  2. <html>
  4. <head>
  5.   <meta charset="UTF-8">
  6.   <title>Elm + Websockets</title>
  7.   <script type="text/javascript" src="elm.js"></script>
  8. </head>
  10. <body>
  11.     <div id="myapp"></div>
  12. </body>
  14. <script type="text/javascript">
  16. // Start the Elm application.
  17. var app = Elm.Main.init({
  18.     node: document.getElementById('myapp')
  19. });
  21. // Create your WebSocket.
  22. var socket = new WebSocket('wss://echo.websocket.org');
  24. // When a command goes to the `sendMessage` port, we pass the message
  25. // along to the WebSocket.
  26. app.ports.sendMessage.subscribe(function(message) {
  27.     socket.send(message);
  28. });
  30. // When a message comes into our WebSocket, we pass the message along
  31. // to the `messageReceiver` port.
  32. socket.addEventListener("message", function(event) {
  33.     app.ports.messageReceiver.send(event.data);
  34. });
  36. // If you want to use a JavaScript library to manage your WebSocket
  37. // connection, replace the code in JS with the alternate implementation.
  38. </script>
  40. </html>

We call Elm.Main.init() like in all of our interop examples, but this time we are actually using the resulting app object. We are subscribing to the sendMessage port and we are sending to the messageReceiver port.

Those correspond to code written on the Elm side.

Ports in Elm

Check out the lines that use the port keyword in the corresponding Elm file. This is how we define the ports that we just saw on the JavaScript side.

  1. port module Main exposing (..)
  3. import Browser
  4. import Html exposing (..)
  5. import Html.Attributes exposing (..)
  6. import Html.Events exposing (..)
  7. import Json.Decode as D
  11. -- MAIN
  14. main : Program () Model Msg
  15. main =
  16.   Browser.element
  17.     { init = init
  18.     , view = view
  19.     , update = update
  20.     , subscriptions = subscriptions
  21.     }
  26. -- PORTS
  29. port sendMessage : String -> Cmd msg
  30. port messageReceiver : (String -> msg) -> Sub msg
  34. -- MODEL
  37. type alias Model =
  38.   { draft : String
  39.   , messages : List String
  40.   }
  43. init : () -> ( Model, Cmd Msg )
  44. init flags =
  45.   ( { draft = "", messages = [] }
  46.   , Cmd.none
  47.   )
  51. -- UPDATE
  54. type Msg
  55.   = DraftChanged String
  56.   | Send
  57.   | Recv String
  60. -- Use the `sendMessage` port when someone presses ENTER or clicks
  61. -- the "Send" button. Check out index.html to see the corresponding
  62. -- JS where this is piped into a WebSocket.
  63. --
  64. update : Msg -> Model -> ( Model, Cmd Msg )
  65. update msg model =
  66.   case msg of
  67.     DraftChanged draft ->
  68.       ( { model | draft = draft }
  69.       , Cmd.none
  70.       )
  72.     Send ->
  73.       ( { model | draft = "" }
  74.       , sendMessage model.draft
  75.       )
  77.     Recv message ->
  78.       ( { model | messages = model.messages ++ [message] }
  79.       , Cmd.none
  80.       )
  84. -- SUBSCRIPTIONS
  87. -- Subscribe to the `messageReceiver` port to hear about messages coming in
  88. -- from JS. Check out the index.html file to see how this is hooked up to a
  89. -- WebSocket.
  90. --
  91. subscriptions : Model -> Sub Msg
  92. subscriptions _ =
  93.   messageReceiver Recv
  97. -- VIEW
  100. view : Model -> Html Msg
  101. view model =
  102.   div []
  103.     [ h1 [] [ text "Echo Chat" ]
  104.     , ul []
  105.         (List.map (\msg -> li [] [ text msg ]) model.messages)
  106.     , input
  107.         [ type_ "text"
  108.         , placeholder "Draft"
  109.         , onInput DraftChanged
  110.         , on "keydown" (ifIsEnter Send)
  111.         , value model.draft
  112.         ]
  113.         []
  114.     , button [ onClick Send ] [ text "Send" ]
  115.     ]
  119. -- DETECT ENTER
  122. ifIsEnter : msg -> D.Decoder msg
  123. ifIsEnter msg =
  124.   D.field "key" D.string
  125.     |> D.andThen (\key -> if key == "Enter" then D.succeed msg else D.fail "some other key")

Notice that the first line says port module rather than just module. This makes it possible to define ports in a given module. The compiler gives a hint about this if it is needed, so hopefully no one gets too stuck on that!

Okay, but what is going on with the port declarations for sendMessage and messageReceiver?

Outgoing Messages (Cmd)

The sendMessage declaration lets us send messages out of Elm.

  1. port sendMessage : String -> Cmd msg

Here we are declaring that we want to send out String values, but we could send out any of the types that work with flags. We talked about those types on the previous page, and you can check out this localStorage example to see a Json.Encode.Value getting sent out to JavaScript.

From there we can use sendMessage like any other function. If your update function produces a sendMessage "hello" command, you will hear about it on the JavaScript side:

  1. app.ports.sendMessage.subscribe(function(message) {
  2.     socket.send(message);
  3. });

This JavaScript code is subscribed to all of the outgoing messages. You can subscribe multiple functions and unsubscribe functions by reference, but we generally recommend keeping things static.

We also recommend sending out richer messages, rather than making lots of individual ports. Maybe that means having a custom type in Elm that represents everything you might need to tell JS, and then using Json.Encode to send it out to a single JS subscription. Many people find that this creates a cleaner separation of concerns. The Elm code clearly owns some state, and the JS clearly owns other state.

Incoming Messages (Sub)

The messageReceiver declaration lets us listen for messages coming in to Elm.

  1. port messageReceiver : (String -> msg) -> Sub msg

We are saying we are going to receive String values, but again, we can listen for any type that can come in through flags or outgoing ports. Just swap out the String type with one of the types that can cross the border.

Again we can use messageReceiver like any other function. In our case we call messageReceiver Recv when defining our subscriptions because we want to hear about any incoming messages from JavaScript. This will let us get messages like Recv "how are you?" in our update function.

On the JavaScript side, we are able to send things to this port whenever we want:

  1. socket.addEventListener("message", function(event) {
  2.     app.ports.messageReceiver.send(event.data);
  3. });

We happen to be sending whenever the websocket gets a message, but you could send at other times as well. Maybe we are getting messages from another data source as well. That is fine, and Elm does not need to know anything about it! Just send the strings through the relevant port.

Notes

Ports are about creating strong boundaries! Definitely do not try to make a port for every JS function you need. You may really like Elm and want to do everything in Elm no matter the cost, but ports are not designed for that. Instead, focus on questions like “who owns the state?” and use one or two ports to send messages back and forth. If you are in a complex scenario, you can even simulate Msg values by sending JS like { tag: "active-users-changed", list: ... } where you have a tag for all the variants of information you might send across.

Here are some simple guidelines and common pitfalls:

  • Sending Json.Encode.Value through ports is recommended. Like with flags, certain core types can pass through ports as well. This is from the time before JSON decoders, and you can read about it more here.

  • All port declarations must appear in a port module. It is probably best to organize all your ports into one port module so it is easier to see the interface all in one place.

  • Ports are for applications. A port module is available in applications, but not in packages. This ensures that application authors have the flexibility they need, but the package ecosystem is entirely written in Elm. We think this will create a stronger ecosystem and community in the long run, and we get into the tradeoffs in depth in the upcoming section on the limits of Elm/JS interop.

  • Ports can be dead code eliminated. Elm has quite aggressive dead code elimination, and it will remove ports that are not used within Elm code. The compiler does not know what goes on in JavaScript, so try to hook things up in Elm before JavaScript.

I hope this information will help you find ways to embed Elm in your existing JavaScript! It is not as glamorous as doing a full-rewrite in Elm, but history has shown that it is a much more effective strategy.