LiveView reached the 1.0 milestone in December 2024. Since then, we’ve been hard at work building some long awaited features and improving the overall LiveView experience.

To update from LiveView 1.0 to 1.1, simply follow the CHANGELOG with the upgrade steps or alternatively run the Igniter upgrade task:

mix archive.install hex igniter_new
mix igniter.upgrade phoenix_live_view

Colocated Hooks

At ElixirConf EU 2023, Chris briefly mentioned colocated hooks to address the friction when you need to write a small JavaScript hook for your HEEx component, which would fit neatly next to your component code, but hooks required you to write that code to a whole separate file, maybe deal with JavaScript imports, etc.; While the feature did not make it into 1.0, in LiveView 1.1, you can now write:

<div id="todos" phx-update="stream" phx-hook=".Sortable">
  ...
</div>
<script :type={Phoenix.LiveView.ColocatedHook} name=".Sortable">
  import Sortable from "@/vendor/sortable"

  export default {
    mounted(){
      let group = this.el.dataset.group
      let sorter = new Sortable(this.el, {
        group: group ? {name: group, pull: true, put: true} : undefined,
        animation: 150,
        dragClass: "drag-item",
        ghostClass: "drag-ghost",
        onEnd: e => {
          let params = {old: e.oldIndex, new: e.newIndex, to: e.to.dataset, ...e.item.dataset}
          this.pushEventTo(this.el, this.el.dataset["drop"] || "reposition", params)
        }
      })
    }
  }
</script>

And LiveView will automatically extract the JavaScript at compile time. The only extra plumbing you need is a new import in your app.js:

  import {LiveSocket} from "phoenix_live_view"
+ import {hooks as colocatedHooks} from "phoenix-colocated/my_app"
  import topbar from "../vendor/topbar"

  const csrfToken = document.querySelector("meta[name='csrf-token']").getAttribute("content")
  const liveSocket = new LiveSocket("/live", Socket, {
    longPollFallbackMs: 2500,
    params: {_csrf_token: csrfToken},
+   hooks: {...colocatedHooks},
  })

There are also two small changes needed in your esbuild configuration to tell it where to find the phoenix-colocated folder. We include that configuration by default for new Phoenix 1.8 apps, and we also have instructions in the changelog for existing apps.

If you carefully read the example code above, you might also have spotted the leading dot in the hook name .Sortable. This is a new feature in LiveView 1.1 to automatically prefix the hook name with the current module. To prevent name conflicts - LiveView hook names are global - when using colocated hooks where a hook is meant to belong to a specific component, LiveView enforces the hook name to be prefixed. This also allows library authors to not think about how to name their hooks. They can just call them .whatever and it is ensured that the name won’t conflict with any other user hooks. This feature is most useful for colocated hooks, but it can also be used with any other hook in your project.

Note that if you happened to name your hooks with a leading dot before LiveView 1.1, you’ll need to adjust those hook names.

Colocated JavaScript

When I first built the colocated hooks feature, José asked “why should it only be about hooks?”. Perhaps we could colocate anything?

Our abstraction for colocated hooks builds upon a feature we call “macro components”. For now, macro components are still a private API, since we want to think them through a little bit more, but the general idea is that you implement some callback that receives an AST representation of the HTML and can transform it. The transformation for colocated hooks is writing the text to a file and dropping it altogether from the rendered page. In a separate step, whenever code is compiled, we check the directory into which the code is extracted and generate a manifest file that contains all the necessary JavaScript imports.

A macro component could also be used to render markdown at compile time or perform compile time syntax highlighting. We hope to ship the API to allow this in LiveView 1.2.

Colocated hooks are built on a more generic Phoenix.LiveView.ColocatedJS module, which contains all the code for writing JavaScript to the phoenix-colocated folder and generating the manifest file. This means that you can use Phoenix.LiveView.ColocatedJS to extract generic JavaScript code, like global event handlers, and colocate those within your components:

def navbar(assigns) do
  ~H"""
  <nav>
    ...
    <.button
      phx-click={
        JS.toggle_class("expanded", to: {:closest, "nav"})
        |> JS.dispatch("nav:store-expanded", to: {:closest, "nav"})
      }
    >
      <.icon name="hero-bars-3" />
    </.button>
  </nav>

  <script :type={Phoenix.LiveView.ColocatedJS}>
    window.addEventListener("DOMContentLoaded", () => {
      const expanded = localStorage.getItem("nav:expanded") === "true";
      const nav = document.querySelector("nav");
      if (expanded) {
        window.liveSocket.js().addClass(nav, "expanded");
      }
    });

    window.addEventListener("nav:store-expanded", (e) => {
      const expanded = localStorage.getItem("nav:expanded") === "true";
      localStorage.setItem("nav:expanded", !expanded);
    })
  </script>
  """
end

This example demonstrates a navbar that stores its expanded state in the browser’s localStorage. You could also write a hook for this, but hooks only execute when the LiveView is mounted, which would often show a noticeable delay between the first load of the page until the expanded state is restored. With colocated JS, any non-hook JavaScript code that belongs to a component can have its code directly inside the HEEx template.

Colocated hooks and JS are most useful for small code snippets. While using a regular <script> tag means that syntax highlighting should work, most editors provide limited or no autocompletion.

Keyed Comprehensions

Rendering lists or other collections of items in LiveView has a potential pitfall: whenever an item in the list is changed, the whole list is re-rendered and sent over the wire.

<ul>
  <li :for={i <- @items}>{i.name}</li>
</ul>

If you change the @items assign, all items are sent again, even if you only added, removed or modified a single one. The Phoenix generators scaffold LiveViews that use streams, which is a mechanism to deal with large collections that was introduced during LiveView v0.18. With streams, the server does not keep the items in memory, which is very useful for large collections. The example above would look like this using streams:

<ul id="items" phx-update="stream">
  <li id={id} :for={{id, i} <- @streams.items}>{i.name}</li>
</ul>

Any change must then use stream management functions like stream_insert/4.

Still, streams are not a one size fits all solution for collections. In some cases you don’t want to deal with the management overhead of streams, you just want to declaratively write your for comprehension and still get an optimized diff over the wire.

LiveView does have another solution for this: LiveComponents.

LiveComponents were the first component abstraction introduced back in LiveView v0.4 to “compartmentalize state, markup, and events”. Because LiveComponents have their own state, they also perform their own change tracking.

<ul>
  <.live_component id={i.id} :for={i <- @items} module={MyListItem} item={i} />
</ul>

With a LiveComponent for each list item, changing a single item in the list only sends the diff for this item (and a list of component IDs!). While this code produces small diffs, it feels a bit clunky to create a whole separate module for the LiveComponent, if all you care about is the diff and you don’t need to handle any events inside the component.

Using LiveComponents to optimize the diff over the wire is not an unknown solution to this problem, but it’s something you need to look for and also easy to forget until you’re tasked with optimizing message sizes. Last year, a proposal was sent in the Elixir forum about introducing a :key attribute which would allow LiveView to optimize diffing in regular :for comprehensions:

<ul>
  <li :for={i <- @items} :key={i.id}>{i.name}</li>
</ul>

Initially, we weren’t sure how to tackle it, but after starting at Dashbit and having a couple discussions with the team, it turned out that LiveComponents could actually be the solution. In the first release candidate of LiveView v1.1, we officially introduced the :key attribute! Under the hood, each list item was still rendered by a LiveComponent, but we introduced some special handling to the variables introduced by :for to allow them to be correctly change tracked.

There were a couple of problems with this though. Because there was still a LiveComponent under the hood, :key only worked on regular HTML tags, not components. LiveComponents are patched separately by morphdom and require a single root element for the patch to be applied to. Since components can render multiple root elements, we cannot guarantee they meet this requirement. Furthermore, there’s still a comprehension involved, sending the list of all component IDs, even when only one actually changed. For small templates, the extra component IDs and slightly different diff structure for LiveComponents could actually lead to more overhead. There was an even bigger problem though: when rendering nested comprehensions, LiveView usually extracts all the static parts of the template into a special “template” section of the diff, only sending it once. With LiveComponents, this sharing breaks. If you then combine keyed and non-keyed comprehensions, you’d get an excessively large diff as LiveView would try to calculate the templates for each LiveComponent separately, sending lots of duplicate strings over the wire. We were not happy with those results, so we decided to start from scratch and completely rewrite how LiveView handles comprehensions.

LiveView 1.1 performs change tracking in comprehensions by default. It does not matter if you write <%= for i <- @items do %>...<% end %> or :for, when no key is given LiveView automatically uses an element’s index as the key. This already improves diffs a lot for cases where few entries in a list change. Using the index can lead to suboptimal situations though: if you prepend an item to the list, most of the time all subsequent items will be considered changed. To help LiveView detect this, a :key can be provided to optimize the diff even further.

In the past, using slots in HEEx could lead to unexpectly large diffs, because LiveView uses a comprehension under the hood to iterate over each slot entry when rendering slots:

<.my_list>
  <:list_item label="Name">
    <.some_component>The name</.some_component>
  </:list_item>
  <:list_item label="Price">{@price}</:list_item>
  <:list_item label="Actions">Something to do</:list_item>
  Some more text.
</.my_list>

Even though there’s no :for in sight, a change to @price would also send the name and actions columns over the wire. This is solved now with the new comprehension handling.

There is one remaining case that we cannot optimize yet: :for on slots.

<.my_list>
  <:list_item :for={item <- @items} label={item.label}>
    {item.text}
  </:list_item>
</.my_list>

If you have a template like this, because of the way slot rendering works at the moment, this cannot use keyed comprehensions for the slots. Furthermore, while you can use :key on components when using :for, you cannot use :key on slots like <:list_item>. Change tracking for anything inside of the <:list_item> is also not optimized in this case and will behave the same as in previous versions of LiveView.

Types for public interfaces

LiveView tries to enable writing rich user interfaces without the need to write large amounts of JavaScript code. Still, sometimes you need more control over what happens on the client - that’s why we have hooks - and every LiveView application ships with an app.js JavaScript file configuring LiveView’s LiveSocket. Most editors have great autocompletion support when working in JavaScript and to make interacting with LiveView’s JavaScript interfaces more pleasing, LiveView 1.1 now ships with type declarations for all of its public JavaScript API.

Because of the way Phoenix configures esbuild by default, you may need to hint your editor to look for types in the deps folder as well by creating an assets/tsconfig.json with the following content:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "*": ["node_modules/*", "../deps/*"]
    },
    "allowJs": true,
    "noEmit": true
  },
  "include": ["js/**/*"]
}

Portals

LiveView tracks each event sent to the server with clocks to prevent outdated server updates from rendering on the client. This required updates to morphdom - the library LiveView uses to efficiently update the DOM - to allow LiveView to apply updates to a cloned DOM tree instead of the real one while it is locked.

Could we also use this to build a “teleportation” feature like <Teleport> in Vue.js or createPortal in React by telling morphdom that instead of applying a patch to the actual element, it should instead apply it to some other element in the DOM? And it turns out that, yes, we can make it work!

First, I wanted to introduce a new binding called phx-portal with the idea that you just annotate an element with that binding and tell LiveView where to teleport it to:

<div id="foo" phx-portal="bar">
  ...
</div>

This had one big problem though: if you try to teleport an element because it would otherwise be invalid, for example a <form> inside another form, browsers would fix the HTML before LiveView had a chance to do the teleportation. The solution to this is to use <template> elements. Moreover, using a template also prevents the non-teleported elements from being seen in the initial disconnected render. So the second iteration of portals looked like this:

<template id="foo" phx-portal="bar">
  <div id="foo">...</div>
</template>

Because of the way template elements work and to ensure that morphdom can correctly apply updates, the template element itself must contain a single HTML element with an ID attribute. Writing this by hand feel awkward though - why should users even know about template elements in the first place? At the time, I let the PR sit for a while, because I somehow didn’t see the rather obvious solution: function components.

We just need to define a function component that accepts an ID, a target and its block content. So the final portal code looks like this:

<.portal id="foo" target="#bar">
  ...
</.portal>

Now, you might ask: when would I need a portal in the first place?

Portals are useful whenever you need to render something that should not be constrained by its surrounding context. If you try to render a simple tooltip which happens to be inside an element with overflow: hidden, you can quickly run into situations where content gets unexpectedly cut off. There are modern solutions to this with the Popover API or things like the native <dialog> element, which we do recommend to try out before resorting to <.portal>, but if you cannot use those for whatever reason, LiveView now ships with a solution.

For a smooth teleportation experience, we also adjusted the internal LiveView event handling code to ensure any events from inside teleported content are properly handled by the correct LiveView. You can even teleport LiveComponents and nested LiveViews through a <.portal> and everything should work as expected.

Moving from Floki to LazyHTML

Earlier this year, Dashbit released lazy_html, a small library based on lexbor, which strives to efficiently create output that “should match that of modern browsers, meeting industry specifications”. This means that LiveViewTest now supports modern CSS selectors like :is() and :has().

This should be mostly backwards compatible with existing tests. The only case where this will affect your tests is if you used Floki specific CSS selectors (fl-contains, fl-icontains) and passed those the element/3 function. Phoenix versions prior to v1.8 generated such a selector when using mix phx.gen.auth. Changing those tests to use the text_filter option included since LiveView v0.12 should be enough to make your tests pass again:

 {:ok, _login_live, login_html} =
   lv
-  |> element(~s|main a:fl-contains("Sign up")|)
+  |> element("main a", "Sign up")
   |> render_click()
   |> follow_redirect(conn, ~p"/users/register")

This changes only affects how LiveView parses your pages during test. If you use any other library in your own tests, you are not required to change them when you update to LiveView v1.1 (although users did report better performance with LazyHTML).

Closing thoughts

So, that’s LiveView 1.1! Please also have a look at the changelog, which contains mostly the same content as this blog post, but also includes a quick update guide and some notes about smaller improvements, such as JS.ignore_attributes and improved HEEx slot and line annotations.

If you have any feedback, please don’t hesitate to post a thread in the Elixir forum or contact me on BlueSky. In case you come across any regressions or new bugs in LiveView 1.1, please open up an issue in the repo.

A massive thank you to Dashbit for sponsoring this work and José Valim for his help implementing and reviewing countless pull requests!

Happy coding!

-Steffen

Note: This release requires Erlang/OTP 25+.

Extensible Tailwind Theming and Components with daisyUI

Phoenix 1.8 extends our built-in tailwindcss support with daisyUI, adding a flexible component and theming system. As a tailwind veteran, I appreciate how daisyUI is just tailwind with components you drop into existing workflows, while also making it simpler to apply consistent styling across your app when desired. And if you’re new or simply want to adjust the overall look and feel, daisyUI’s theming lets you make broad changes with just a few config tweaks. No fiddly markup rewrites required. Check out daisyUI’s theme generator to see what’s possible.

Note: the phx.gen.* Generators do not depend on daisyUI, and because it is a tailwind plugin, it is easy to remove and leaves no additional footprints

All phx.new apps now ship with light and dark themes out of the box, with a toggle built into the layout. Here’s the landing page and a phx.gen.live form:

Forms, rounding, shadows, typography, and more can all be adjusted with simple config changes to your app.css. This is all possible thanks to daisyUI. We also ship with the latest and greatest from the recent tailwind v4 release.

Magic Link / Passwordless Authentication by default

The phx.gen.auth generator now uses magic links by default for login and registration.

If you’re a password enthusiast, don’t fret — standard email/pass auth remains opt-in via user settings.

Magic links offer a user-friendly and secure alternative to regular passwords. They’ve grown in popularity for good reason:

• No passwords to remember – fewer failed logins or locked accounts
• Faster onboarding, especially from mobile devices

We also include a require_sudo_mode plug, which can be used for pages that contain sensitive operations and enforces recent authentication.

Our generators handle all the security details for you, and with the Dev Preview Mailbox, your dev workflow stays hassle free. Thanks to our integration with Swoosh, your email-backed auth system is ready to go the moment you’re ready to ship to prod.

Let’s see it in action:

Scopes for data access and authorization patterns that grow with you

Scopes are a new first-class pattern in Phoenix, designed to make secure data access the default, not something you remember (or forget) to do later. Reminder that broken access control is the most common OWASP vulnerability.

Scopes also help your interfaces grow with your application needs. Think about it as a container that holds information that is required in the huge majority of pages in your app. It can also hold important request metadata, such as IP addresses for rate limiting or audit tracking.

Generators like phx.gen.live, phx.gen.html, and phx.gen.json now use the current scope for generated code. From the original request, the tasks automatically thread the current scope through all the context functions like list_posts(scope) or get_post!(scope, id), ensuring your application stays locked down by default. This gives you scoped data access (queries and PubSub!), automatic filtering by user or organization, and proper foreign key fields in migrations – all out of the box.

And scopes are simple. It’s just a plain struct in your app that your app wholly owns. The moment you run phx.gen.auth, you gain a new %MyApp.Accounts.Scope{} data structure that centralizes the information for the current request or session — like the current user, their organization, or anything else your app needs to know to securely load and manipulate data, or interact with the system.

Scopes also scale with your codebase. You can define multiple scopes, augment existing ones, such as adding an :organization field to your user scope, or even configure how scope values appear in URLs for user-friendly slugs.

Scopes aren’t just a security feature. They provide a foundation for building multi-tenant, team-based, or session-isolated apps, slot cleanly into the router and LiveView lifecycle, and stay useful even outside the context of a request. Think role verification, or programmatic access patterns where you need to know if a call came from the system or an end-user.

Be sure to check out the full scopes guide for in depth instructions on using scopes in your own applications, but let’s walk through a quick example from the guide.

Integration of scopes in the Phoenix generators

If a default scope is defined in your application’s config, the generators will generate scoped resources by default. The generated LiveViews / Controllers will automatically pass the scope to the context functions. mix phx.gen.auth automatically sets its scope as default, if there is not already a default scope defined:

# config/config.exs
config :my_app, :scopes,
  user: [
    default: true,
    ...
  ]

Let’s look at the code generated once a default scope is set:

$ mix phx.gen.live Blog Post posts title:string body:text

This creates a new Blog context, with a Post resource. To ensure the scope is available, for LiveViews the routes in your router.ex must be added to a live_session that ensures the user is authenticated:

   scope "/", MyAppWeb do
     pipe_through [:browser, :require_authenticated_user]

     live_session :require_authenticated_user,
       on_mount: [{MyAppWeb.UserAuth, :ensure_authenticated}] do
       live "/users/settings", UserLive.Settings, :edit
       live "/users/settings/confirm-email/:token", UserLive.Settings, :confirm_email

+      live "/posts", PostLive.Index, :index
+      live "/posts/new", PostLive.Form, :new
+      live "/posts/:id", PostLive.Show, :show
+      live "/posts/:id/edit", PostLive.Form, :edit
     end

     post "/users/update-password", UserSessionController, :update_password
   end

Now, let’s look at the generated LiveView (lib/my_app_web/live/post_live/index.ex):

defmodule MyAppWeb.PostLive.Index do
  use MyAppWeb, :live_view

  alias MyApp.Blog

  ...

  @impl true
  def mount(_params, _session, socket) do
    Blog.subscribe_posts(socket.assigns.current_scope)

    {:ok,
     socket
     |> assign(:page_title, "Listing Posts")
     |> stream(:posts, Blog.list_posts(socket.assigns.current_scope))}
  end

  @impl true
  def handle_event("delete", %{"id" => id}, socket) do
    post = Blog.get_post!(socket.assigns.current_scope, id)
    {:ok, _} = Blog.delete_post(socket.assigns.current_scope, post)

    {:noreply, stream_delete(socket, :posts, post)}
  end

  @impl true
  def handle_info({type, %MyApp.Blog.Post{}}, socket)
      when type in [:created, :updated, :deleted] do
    {:noreply, stream(socket, :posts, Blog.list_posts(socket.assigns.current_scope), reset: true)}
  end
end

Note that every function from the Blog context that we call gets the current_scope assign passed in as the first argument. The list_posts/1 function then uses that information to properly filter posts:

# lib/my_app/blog.ex
def list_posts(%Scope{} = scope) do
  Repo.all(from post in Post, where: post.user_id == ^scope.user.id)
end

The LiveView even subscribes to scoped PubSub messages and automatically updates the rendered list whenever a new post is created or an existing post is updated or deleted, while ensuring that only messages for the current scope are processed.

Streamlined Onboarding

Phoenix v1.7 introduced a unified developer experience for building both old-fashioned HTML apps and realtime interactive apps with LiveView. This made LiveView and HEEx function components front and center as the new building blocks for modern Phoenix applications.

As part of this effort, we introduced a core_components.ex file that provides declarative components to use throughout your app. Those components were the back-bone of the phx.gen.html code generator as well as the new phx.gen.live task. Phoenix developers would then evolve those components over time, as needed by their applications.

While these additions were useful to showcase what you can achieve with Phoenix LiveView, they would often get in the way of experienced developers, by generating too much opinionated code. At the same time, they could also overwhelm someone who was just starting with Phoenix.

Now, after receiving feedback from new and senior developers alike, and with Phoenix LiveView 1.0 officially out, we chose to simplify several of our code generators. Our goal is to give seasoned folks a better foundation to build the real features they want to ship, while giving newcomers simplified code which will help them get up to speed on the basics more quickly:

The mix phx.gen.live generator now follows its sibling, mix phx.gen.html, to provide a straight-forward CRUD interface you can build on top of, while showcasing the main LiveView concepts. In turn, this allows us to trim down the core components to only the main building blocks.

Even the mix phx.gen.auth generator, which received the magic link support and sudo mode mentioned above, does so in fewer files, fewer functions, and fewer lines of code.

The context guide has been broken apart into a few separate guides that now better explores data modeling, using ecommerce to drive the examples.

We also have new guides for authentication and authorization, which combined with scopes, gives you a solid starting point to designing secure and maintainable projects.

Simplified Layouts

We have also revised Phoenix nested layouts, root.html.heex and app.html.heex, in favor of a single layout that is then augmented with function components.

Previously, root.html.heex was the static layout and app.html.heex was the dynamic one that can be updated throughout the lifecycle of your LiveViews. This remains the case, but the app layout usage in 1.8 has been simplified.

Our prior approach set apps up with a fixed app layout via use Phoenix.LiveView, layout: ... options, which could be confusing and also required too much ceremony to support multiple app layouts programmatically. Instead, root layout remains unchanged, while the app layout has been made an explicit function component call wherever you want to include a dynamic app layout.

Here is an example of how we could augment the new app layout in Phoenix with breadcrumbs and then easily reuse them across pages.

First, we’d add an optional :breadcrumb slot to our <Layouts.app> function component, which renders the breadcrumbs above the caller’s inner block:

defmodule AppWeb.Layouts do
  use AppWeb, :html

  embed_templates "layouts/*"

  slot :breadcrumb, required: false

  def app(assigns)
    ~H"""
    ...
    <main class="px-4 py-20 sm:px-6 lg:px-8">
      <div :if={@breadcrumb != []} class="py-4 breadcrumbs text-sm">
        <ul>
          <li :for={item <- @breadcrumb}>{render_slot(item)}</li>
        </ul>
      </div>
      <div class="mx-auto max-w-2xl space-y-4">
        {render_slot(@inner_block)}
      </div>
    </main>
    """
  end
end

Then in any of our LiveViews that want breadcrumbs, the caller can declare them:

@impl true
def render(assigns) do
  ~H"""
  <Layouts.app flash={@flash}>
    <:breadcrumb>
      <.link navigate={~p"/posts"}>All Posts</.link>
    </:breadcrumb>
    <:breadcrumb>
      <.link navigate={~p"/posts/#{@post}"}>View Post</.link>
    </:breadcrumb>
    <.header>
      Post {@post.id}
      <:subtitle>This is a post record from your database.</:subtitle>
      <:actions>
        <.link class="btn" navigate={~p"/posts/#{@post}/edit"}>Edit post</.link>
      </:actions>
    </.header>
    <p>
      My LiveView Page
    </p>
  </Layouts.app>
  """
end

And this is what it looks like in action:

Notice how the app layout is now an explicit call. If you have other app layouts, like a cart page, admin page, etc, you simply write a new <Layouts.admin flash={@flash}>, passing whatever assigns you need.

Supporting something like this with our prior app layout approach would have required feeding assigns to the app layout and branching based on some conditions, and mucking with app_web.ex to support additional layout options. Now, the caller is simply free to handle their layout concerns inline.

Combined with daisyUI component classes, the streamlined layouts and onboarding experience offers a fantastic starting point for rapid development, with easy customization and a robust component system to choose from.

Try it out

You can update existing phx.new installations with:

mix archive.install hex phx_new 1.8.0-rc.0 --force

Reminder, we launched new.phoenixframework.org several months ago which lets you get up and running in seconds with Elixir and your first Phoenix project with a single command.

You can use it to take Phoenix v1.8 release candidate for a spin:

For osx/linux:

$ curl https://new.phoenixframework.org/myapp | sh

For Windows PowerShell:

> curl.exe -fsSO https://new.phoenixframework.org/app.bat; .\app.bat

Phoenix 1.8 brings improvements to developer productivity and app structure, from scoped data access that grows with your domain to tailwind theming that grows with your design. Combined with passwordless auth and lighter generators this release should streamline your app development whether you’re a new user or building along with us for the last 10 years.

Huge shoutout to Steffen Deusch and his Dashbit sponsored work for making the majority of the features here happen!

Note: This is a backwards compatible release with a few deprecations.

As always, find us on elixirforum, slack, or discord if you have questions or need help.

Happy coding!

–Chris

This 1.0 milestone comes six years after the first LiveView commit.

Why LiveView

I started LiveView to scratch an itch. I wanted to create dynamic server-rendered applications without writing JavaScript. I was tired of the inevitable ballooning complexity that it brings.

Think realtime form validations, updating the quantity in a shopping cart, or real-time streaming updates. Why does it require moving mountains to solve in a traditional stack? We write the HTTP glue or GraphQL schemas and resolvers, then we figure out which validation logic needs shared or dup’d. It goes on and on from there – how do we get localization information to the client? What data serializers do we need? How do we wire up WebSockets and IPC back to our code? Is our js bundle getting too large? I guess it’s time to start turning the Webpack or Parcel knobs. Wait Vite is a thing now? Or I guess Bun configuration is what we want? We’ve all felt this pain.

The idea was, what if we removed these problems entirely? HTTP can go away, and the server can handle all the rendering and dynamic update concerns. It felt like a heavy approach, but I knew Elixir and Phoenix was perfectly suited for it.

Six years later this programming model still feels like cheating. Everything is super fast. Payloads are tiny. Latency is best-in-class. Not only do you write less code, there’s simply less to think about when writing features.

Real-time foundations unlock superpowers

Interesting things happen when you give every user and UI a real-time, bidirectional foundation as a matter of course. You suddenly have superpowers. You almost don’t notice it. Being freed from all the mundane concerns of typical full-stack development lets you focus on just shipping features. And with Elixir, you start shipping features that other platforms can’t even conceive as possible.

Want to ship real-time server logs to the js console in development? No problem!

What about supporting production hot code upgrades where browsers can auto re-render anytime CSS stylesheets, images, or templates change – without losing state or dropping connections? Sure!

Or maybe you have an app deployed planet-wide where you do work across the cluster and aggregate the results in real-time back to the UI. Would you believe the entire LiveView, including the template markup and RPC calls, is 350 LOC?

These are the kinds of applications that LiveView enables. It feels incredible to ship these kinds of things, but it took a while to arrive here for good reasons. There was a lot to solve to make this programming model truly great.

How it started

Conceptually, what I really wanted is something like what we do in React – change some state, our template re-renders automatically, and the UI updates. But instead of a bit of UI running on the client, what if we ran it on the server? The LiveView could look like this:

defmodule ThermoLive do
  def render(assigns) do
    ~H"""
    <div id="thermostat">
      <p>Temperature: {@thermostat.temperature}</p>
      <p>Mode: {@thermostat.mode}</p>
      <button phx-click="inc">+</button>
      <button phx-click="dec">-</button>
    </div>
    """
  end

  def mount(%{"id" => id}, _session, socket) do
    thermostat = ThermoControl.get_thermostat!(id)
    :ok = ThermoControl.subscribe(thermostat)
    {:ok, assign(socket, thermostat: thermostat)}
  end

  def handle_info({ThermoControl, %ThermoStat{} = new_thermo}, _, socket) do
    {:noreply, assign(socket, thermostat: new_thermo)}
  end

  def handle_event("inc", _, socket) do
    thermostat = ThermoControl.inc(socket.assigns.thermostat)
    {:noreply, assign(socket, thermostat: thermostat)}
  end
end

Like React, we have a render function and something that sets our initial state when the LiveView mounts. When state changes, we call render with the new state and the UI is updated.

Interactions like phx-click on the + or - button, can be sent as RPC’s from client to server and the server can respond with fresh page HTML. These client/server messages use Phoenix Channels which scale to millions of connections per server.

Likewise, if the server wants to send an update to the client, such as another user changing the thermostat, the client can listen for it and replace the page HTML in the same fashion. My naive first pass on the phoenix_live_view.js client looked something like this.

let main = document.querySelector("[phx-main]")
let channel = new socket.channel("lv")
channel.join().receive("ok", ({html}) => main.innerHTML = html)
channel.on("update", ({html}) => main.innerHTML = html)

window.addEventListener("click", e => {
  let event = e.getAttribute("phx-click")
  if(!event){ return }
  channel.push("event", {event}).receive("ok", ({html}) => main.innerHTML = html)
})

This is how LiveView started. We went to the server for interactions, re-rendered the entire template on state change, and sent the entire page down to the client. The client then swapped out the inner HTML.

It worked, but it was not great. Partial state changes required re-executing the entire template and sending down gobs of HTML for otherwise tiny updates.

Still the basic programming model was exactly what I wanted. As HTTP fell away from my concerns, entire layers of full-stack considerations disappeared.

Next the challenge was making this something truly great. Little did we know we’d accidentally our way to outperforming many SPA use-cases along the way.

How we optimized the programming model

LiveView’s diffing engine solved two problems with a single mechanism. The first problem was only executing those dynamic parts of a template that actually changed from a previous render. The second was only sending the minimal data necessary to update the client.

It solves both by splitting the template into static and dynamic parts. Considering the following LiveView template:

~H"""
<p class={@mode}>Temperature: {format_unit(@temperature)}</p>
"""

At compile time, we convert the template into a struct like this:

%Phoenix.LiveView.Rendered{
  static: ["<p class=\"", "\">Temperature:", "</p>"]
  dynamic: fn assigns ->
    [
      if changed?(assigns, :mode), do: assigns.mode,
      if changed?(assigns, :temperature), do: format_unit(assigns.temperature)
    ]
  end
}

We know the static parts never change, so they are split from the dynamic Elixir expressions. Next, we compile each expression with change tracking based on the variables accessed within each expression. On render, we compare the previous template values with the new and only execute the template expression if the value has changed.

Instead of sending the entire template down on change, we can send the client all the static and dynamic parts on mount. After mount we only send the partial diff of dynamic values for each update.

To see how this works, we can imagine the following payload being sent on mount for the template above:

{
  s: ["<p class=\"", "\">Temperature: ", "</p>"],
  0: "cooling",
  1: "68℉"
}

The client receives a map of static values in the s key, and dynamic values keyed by their index in the statics. For the client to render the full template string, it only needs to zips the static list with the dynamic values. For example:

["<p class=\"", "cooling", "\">Temperature: ", "68℉", "</p>"].join("")
"<p class=\"cooling\">Temperature: 68℉</p>"

With the client holding a static/dynamic cache, optimizing network updates is no work at all. Any server render following mount simply returns the new dynamic values at their known index. Unchanged dynamic values and statics are ignored entirely.

If a LiveView runs assign(socket, :temperature, 70), the render/1 function is invoked, and the following payload gets sent down the wire:

{1: "70℉"}

Thats it! To update the UI, the client simply merges this object with its static/dynamic cache:

{                     {
                        s: ["<p class=\"", "\">Temperature: ", "</p>"],
                        0: "cooling",
  1: "70F"     =>       1: "70℉"
}                     }

Then the data is zipped together on the client to produce the full HTML of the UI.

Of course innerHTML updates blow away UI state and are expensive to perform. So like any client-side framework, we compute minimal DOM diffs to efficiently update the DOM. In fact, we’ve had folks migrate from React to Phoenix LiveView because LiveView client rendering was faster what their React app could offer.

Optimizations continued from there. Including fingerprinting, for comprehensions, tree sharing, and more. You can read all about each optimization on the Dashbit blog.

We apply these optimizations automatically and for free thanks to our stateful client and server connection. Most other server rendered HTML solutions send the whole fragment on every update or require users to fine tune updates by hand.

Best in class latency

We’ve seen how LiveView payloads are smaller than the best hand-written JSON API or GraphQL query, but it’s even better than that. Every LiveView holds a connection to the server so page navigation happens via live navigation. TLS handshakes, current user auth, etc happen a single time for the lifetime of the user’s visit. This allows page navigation to happen via a single WebSocket frame, and fewer database queries for any client action. The result is fewer round trips from the client, and simply less work done by the server. This provides less latency for the end-user compared to an SPA fetching data or sending mutations up to a server.

Holding a stateful connections comes at the cost of server memory, but it’s far cheaper than folks expect. At a baseline, a given channel connection consumes 40kb of memory. This gives a 1GB server a theoretical ceiling of ~25,000 concurrent LiveViews. Of course the more state you store, the more memory you consume, but you only hold onto the state you need. We also have stream primitives for handling large collections without impacting memory. Elixir and the Erlang VM were designed for this. Scaling a stateful system to millions of concurrent users isn’t theoretical – we do it all the time. See WhatsApp, Discord, or our own benchmarks as examples.

With the programming model optimized on both client and server, we expanded into higher level building blocks that take advantage of our unique diffing engine.

Reusable Components with HEEx

Change tracking and minimal diffs were ground-breaking features, but our HTML templates still lacked composability. The best we could offer is “partial”-like template rendering where a function could encapsulate some partial template content. This works, but it composes poorly and is mismatched in the way we write markup. Fortunately Marlus Saraiva from the Surface project spearheaded development of an HTML-aware component system and contributed back to the LiveView project. With HEEx components, we have a declarative component system, HTML validation, and compile-time checking of component attributes and slots.

HEEx components are just annotated functions. They look like this:

@doc """
Renders a button.

## Examples

    <.button>Send!</.button>
    <.button phx-click="go">Send!</.button>
"""
attr :type, :string, default: nil
attr :rest, :global, include: ~w(disabled form name value)

slot :inner_block, required: true

def button(assigns) do
  ~H"""
  <button
    type={@type}
    class="rounded-lg bg-zinc-900 hover:bg-zinc-700 py-2 px-3 text-white"
    {@rest}
  >
    {render_slot(@inner_block)}
  </button>
  """
end

An invalid call to a component, such as <.button click="bad"> produces a compile-time warning:

warning: undefined attribute "click" for component AppWeb.CoreComponents.button/1
  lib/app_web/live/page_live.ex:123: (file)

Slots allows the component to accept arbitrary content from a caller. This allows components to be much more extensible by the caller without creating a bunch of bespoke partial templates to handle every scenario.

Streamlined HEEx syntax

When we introduced HEEx and function components, we added a new syntax for interpolating values within tag attributes along with :if and :for conveniences for conditionally generating templates. It looked like this:

<div :if={@some_condition?}>
  <ul>
    <li :for={val <- @values}>Value <%= val %></li>
  </ul>
</div>

Note the use of standard EEx <%= %> interpolation. With the release of LiveView 1.0, we are extending the HTML-aware {} attribute interpolation syntax to within tag bodies as well. This means you can now interpolate values directly within the tag body in a streamlined syntax:

<div :if={@some_condition?}>
  <ul>
    <li :for={val <- @values}>Value {val}</li>
  </ul>
</div>

The EEx <%= %> remains supported and is required for generating dynamic blocks of distinct markup, as well as for interpolating values within <script> and <style> tags.

HEEx markup annotations

Gone are the days of examining your browser’s HTML and then hunting for where that HTML was generated within your code. The final browser markup can be rendered within several nested layers of component calls. How do we quickly trace back who rendered what?

HEEx solves this with a debug_heex_annotations configuration. When set, all rendered markup will be annotated with the file:line of the function component definition, as well as, the file:line of the caller invocation of the component. In practice your dev HTML will look like this in the browser inspector:

It annotates the document both at the caller site and the function component definition. If you find the above hard to navigate, you can use the new Phoenix.LiveReloader features that have your editor jump to an element’s nearest caller or definition file:line when clicked with a special key sequence of your choosing.

Let’s see it in action:

First, we can see how holding c while clicking jumped to the caller file:Line location for that <.button> invocation. Next, we see that holding d while clicking the button jumped to the function definition file:line.

This is such a simple quality of life improvement. It will become a key part of your workflow as soon as you try it out.

Interactive Uploads

A few years ago, LiveView tackled the file upload problem. Something that should be easy has historically been unnecessarily difficult. We wanted a single abstraction for interactive uploads for both direct to cloud, and direct to server use-cases.

With a few lines of server code you can have file uploads with drag and drop, file progress, selection pruning, file previews, and more.

More recently, we defined an UploadWriter behavior. This gives you access to the raw upload stream as it’s being chunked by the client. This lets you do things like stream uploads to a different server or transcode a video as it’s being uploaded.

Since the uploads happen over the existing LiveView connection, reflecting the upload progress or advanced file operations become trivial to implement:

Streams and Async

Following uploads, we shipped a streams primitive for efficiently handling large collections without needing to hold those collections in server memory. We also introduced assign_async and start_async primitives, which makes handling async operations and rendering async results a breeze.

For example, imagine you have an expensive operation that calls out to an external service. The results can be latent or spotty, or both. Your LiveView can use assign_async/2 to offload this operation to a new process and <.async_result> to render the results with each loading, success, or failure state.

def render(assigns) do
  ~H"""
  <.async_result :let={org} assign={@org}>
    <:loading>Loading organization <.spinner /></:loading>
    <:failed :let={_failure}>there was an error loading the organization</:failed>
    {org.name}
  </.async_result>
  """
end

def mount(%{"slug" => slug}, _, socket) do
  {:ok, assign_async(:org, fn -> {:ok, %{org: fetch_org(slug)}} end)}
end

Now instead of worrying about an async task crashing the UI, or carefully monitoring async ops while updating the template with a bunch of conditionals, you have a single abstraction for performing the work and rendering the results. As soon as the LiveView disconnects, the async processes are cleaned up, ensuring no wasted resources go to a UI that is no longer around.

Here we can also see slots in action with the <:loading> and <:failed> slots of the <.async_result> function component. Slots allow the caller to extend components with their own dynamic content, including their own markup and function component calls.

LiveView goes mainstream

LiveView and .NET Blazor both started about the same time. I like to think both projects helped spearhead the adoption of this programming model.

Since getting started, this model has been embraced in various ways in the Go, Rust, Java, PHP, JavaScript, Ruby, and Haskell communities. And I’m sure others I haven’t yet heard of.

Most don’t offer LiveView’s declarative model. Instead developers are required to annotate how individual elements are updated and removed, leading to fragile applications, akin to client-side applications before the introduction of React and other declarative frameworks. Most also lack the optimizations LiveView developers get for free. Large payloads are sent on every event unless developers manually fine tune them.

React itself liked the idea of putting React on the server so much, they shipped their own React Server Components to tackle a cross section of similar goals with LiveView. In the case of RSC, pushing real-time events are left to external means.

React, like most, chose different tradeoffs because they had no choice. The majority skip the stateful, bidirectional communication layer because most platforms are poorly suited for it. Elixir and the Erlang VM are truly what make this programming model shine. And we have only barely discussed our built-in globally distributed clustering and PubSub. There are truly extraordinary features built into the platform that are at your fingertips.

Try it out

Now is a great time to dive in and give LiveView a try! We have launched new.phoenixframework.org which lets you get up and running in seconds with Elixir and your first Phoenix project with a single command:

For osx/linux:

$ curl https://new.phoenixframework.org/myapp | sh

For Windows PowerShell:

> curl.exe -fsSO https://new.phoenixframework.org/app.bat; .\app.bat

For existing applications, check the changelog for breaking changes to bring your existing apps up to speed.

What’s Next

Following this release, we’ll be continuing efforts around collocated JavaScript hooks, enhancing Web Component integration, supporting navigation guards, and more as outlined in our issue tracker.

Special Thanks

Arriving here wouldn’t have been possible without the help of the Phoenix team, especially Steffen Deusch, who has tackled countless LiveView issues over the last year.

Happy Hacking!

–Chris

Open source TodoTrek showcase application

As demo’d and as promised in my ElixirConfEU keynote, I’m open sourcing the TodoTrek application, a Trello-like app which showcases the new stream features like drag-and-drop, infinite scrolling, dynamic forms, and more.

Here’s TodoTrek in action:

Now onto the features!

Enhanced Stream interface with resets and limits

Streams in LiveView 0.18 introduced a powerful way to handle large collections on the client without storing the collection in server memory. Streams allow developers to append, prepend, or arbitrary insert and update items in collection on the UI. This opened the door to many SPA-like usecases, such as realtime timelines, and infinite feeds, but a couple primitives were lacking.

With LiveView 0.19, streams close the gap on those primitives. Streams can be limited on the UI with the :limit option. This allows the developer to instruct the UI to keep the first N, or N items in collection when inserting new items to a stream. This is essential for a number of cases, such as the prevention of overwhelming clients with too much data in the DOM. Combined with new viewport bindings, virtualized, infinite lists can be implemented effortless, which we’ll see in a moment.

In addition to stream limits, streams also now support a :reset optionw, whichs clears the stream container on the client when updating the stream. This is useful for any case you need to clear results or reset a list, such as search autocomplete, or traditional pagination.

With just a simple stream(socket, :posts, posts, limit: 10) or stream(socket, :posts, [], reset: true), you can now accomplish complex client collection handling without having to think about it. But that’s just the start of what’s possible.

Nested streams with drop-in drag and drop

LiveView 0.19 supports nested streams, which allows drag and drop to be implemented in just a few lines of code. Imagine a trello board where your have named lists holding todo items. You can drag an drop re-order the lists themselves, or todos within the lists. You can also drag and drop todos across lists. All this is possible in LiveView now with a shockingly small amount of code on the client and server. For client-side drag-and-drop itself, you can bring your own library and integrate with a dozen of lines of code. For example, here’s the TodoTrek drag and drop for handling todos and lists:

import Sortable from "../vendor/sortable"
Hooks.Sortable = {
  mounted(){
    let group = this.el.dataset.group
    let sorter = new Sortable(this.el, {
      group: group ? {name: group, pull: true, put: true} : undefined,
      animation: 150,
      dragClass: "drag-item",
      ghostClass: "drag-ghost",
      onEnd: e => {
        let params = {old: e.oldIndex, new: e.newIndex, to: e.to.dataset, ...e.item.dataset}
        this.pushEventTo(this.el, this.el.dataset["drop"] || "reposition", params)
      }
    })
  }
}

Here we import sortable.js, then wire it up as a phx-hook. Now any stream container can wire up streams with drag-and-drop with the following markup:

<div id="todos" phx-update="stream" phx-hook="Sortable">
  ...
</div>

When an item is dropped, the LiveView will receive a “reposition” event with the new and old indexes, plus whatever data attributes exists.

Viewport bindings for virtualized, infinite scrolling

LiveView 0.19 introduces two new phx bindings for handling viewport events – phx-viewport-top and phx-viewport-bottom. These events a triggered when the first child of a container reaches the top of the viewport, or the last child reaches the bottom of the viewport. Combining these two events with stream limits, allows you to perform “virtualzed” infinite scrolling, where only a small set of the items exist in the DOM, while the user experiences the list a large, or infinite set of items. Prior to LiveView 0.19, this kind of feature required users to escape to complex JavaScript hooks, but no more.

Dynamic forms with new inputs_for

Dynamicaly adding and removing inputs with inputs_for is now supported by rendering checkboxes for inserts and removals. Libraries such as Ecto, or custom param filtering, can inspect the paramters and handle the added or removed fields. This can be combined with Ecto.Changeset.cast/3‘s :sort_param and :drop_param options. For example, imagine a parent Ecto.Schema with an :emails has_many or embeds_many association. To cast the user input from a nested inputs_for, one simply needs to configure the options:

schema "lists" do
  field :title, :string

  embeds_many :emails, EmailNotification, on_replace: :delete do
    field :email, :string
    field :name, :string
  end
end

def changeset(list, attrs) do
  list
  |> cast(attrs, [:title])
  |> cast_embed(:emails,
    with: &email_changeset/2,
    sort_param: :emails_sort,
    drop_param: :emails_drop
  )
end

Here we see the :sort_param and :drop_param options in action.

Note: on_replace: :delete on the has_many and embeds_many is required when using these options.

When Ecto sees the specified sort or drop parameter from the form, it will sort the children based on the order they appear in the form, add new children it hasn’t seen, or drop children if the drop parameter intructs it to do so.

The markup for such a schema and association would look like this:

<.inputs_for :let={ef} field={@form[:emails]}>
  <input type="hidden" name="list[emails_sort][]" value={ef.index} />
  <.input type="text" field={ef[:email]} placeholder="email" />
  <.input type="text" field={ef[:name]} placeholder="name" />
  <label>
    <input type="checkbox" name="list[emails_drop][]" value={ef.index} class="hidden" />
    delete
  </label>
</.inputs_for>

<label class="block cursor-pointer">
  <input type="checkbox" name="list[emails_sort][]" class="hidden" />
  add more
</label>

We used inputs_for to render inputs for the :emails association, which containes an email address and name input for each child. Within the nested inputs, we render a hidden list[emails_sort][] input, which is set to the index of the given child. This tells Ecto’s cast operation how to sort existing children, or where to insert new children. Next, we render the email and name inputs as usual. Then we render a label containing the “delete” text and a hidden checkbox input with the name list[emails_drop][], containing the index of the child as its value. Like before, this tells Ecto to delete the child at this index when the checkbox is checked. Wrapping the checkbox and textual content in a label makes any clicked content within the label check and uncheck the checkbox.

Finally, outside the inputs_for, we render another label with a value-less list[emails_sort][] checkbox with accompanied “add more” text. Ecto will treat unknown sort params as new children and build a new child.

One great thing about this approach is allows both LiveView and traditional views to use the same form and casting primitives.

Closing the gap on what’s possible

The features in 0.19 allows effortless implementation of all kinds of usecases previously relegated to single page applications. Think chat messaging with infinite scroll history like Slack, or bidirectional social timelines like Twitter, or Todo apps like Trello with nested drag and drop re-ordering. It’s now possible without having to even think about the necesary details on the client. This release sets us up to focus on getting LiveView 1.0 out the door. Stay tuned!

Happy coding!

–Chris

Easier Tailwind opt-out

Phoenix 1.7 included tailwindcss by default along with a new form component-based architecture. This makes it super easy to opt-out of Tailwind in favor for another tool or custom CSS, but there were still a few manual steps. Namely, you needed to remove the tailwind.config.js file and the dev :watchers configuration. We introduced a mix phx.new --no-tailwind flag to let folks skip these steps when generating a new project.

Channel and LiveView Socket Draining

Cold deploys at high scale for stateful apps like channels or LiveView can be challenging to orchestrate. Deploys often involve custom tuning your deploy tools or proxies to roll out the release slowly to avoid overloading the new servers with a thundering herd of traffic. Phoenix 1.7.2 introduces a new channel socket drain feature, which orchestrates a batched, staged drain process on application shutdown. Draining is enabled by default and you can configure the shutdown from the socket macro in your endpoint.

From the docs:

  @doc """
  ...
  * `:drainer` - a keyword list configuring how to drain sockets
    on application shutdown. The goal is to notify all channels (and
    LiveViews) clients to reconnect. The supported options are:

    * `:batch_size` - How many clients to notify at once in a given batch.
      Defaults to 10000.
    * `:batch_interval` - The amount of time in milliseconds given for a
      batch to terminate. Defaults to 2000ms.
    * `:shutdown` - The maximum amount of time in milliseconds allowed
      to drain all batches. Defaults to 30000ms.

  For example, if you have 150k connections, the default values will
  split them into 15 batches of 10k connections. Each batch takes
  2000ms before the next batch starts. In this case, we will do everything
  right under the maximum shutdown time of 30000ms. Therefore, as
  you increase the number of connections, remember to adjust the shutdown
  accordingly. Finally, after the socket drainer runs, the lower level
  HTTP/HTTPS connection drainer will still run, and apply to all connections.
  Set it to `false` to disable draining.
  """

If you’re not operating at high scale, you don’t need to to worry about this feature, but it will be there and waiting when you need it. If you’re already operating at high scale, this feature should make deploys less stressful on your infrastructure or allow you to ditch cloud-specific configuration.

JS.exec

We introduced a new JS command for executing an existing command on the page located on another DOM element. This greatly optimizes payloads in certain cases that otherwise involved shoving the same duplicated command in the DOM multiple times. For example, the default modal in your core_components.ex module previously contained a duplicated command for closing the modal in multiple places:

  def modal(assigns) do
    ~H"""
    <div
      id={@id}
      phx-mounted={@show && show_modal(@id)}
      phx-remove={hide_modal(@id)}
    >
      <div id={"#{@id}-bg"}>
      <div>
        <div class="flex min-h-full items-center justify-center">
          <div class="w-full max-w-3xl p-4 sm:p-6 lg:py-8">
            <.focus_wrap
              id={"#{@id}-container"}
              phx-window-keydown={hide_modal(@on_cancel, @id)}
              phx-key="escape"
              phx-click-away={hide_modal(@on_cancel, @id)}
    """
  end

We had the same command for phx-window-keydown and phx-click-away, and a similar command on phx-remove. These hide the modal and invoke the caller’s own command both on ESC and when clicking outside the modal, and transition the modal when the user navigates away. This produces a sizable payload when the JS commands contain things like transitions with their own classes and timing values. We can cut the payload by more than half by specifying the command only once and telling LiveView where it can execute it. The new modal looks like this:

  def modal(assigns) do
    ~H"""
    <div
      id={@id}
      phx-mounted={@show && show_modal(@id)}
      phx-remove={hide_modal(@id)}
      data-cancel={JS.exec(@on_cancel, "phx-remove")}
    >
      <div id={"#{@id}-bg"}>
      <div>
        <div class="flex min-h-full items-center justify-center">
          <div class="w-full max-w-3xl p-4 sm:p-6 lg:py-8">
            <.focus_wrap
              id={"#{@id}-container"}
              phx-window-keydown={JS.exec("data-cancel", to: "##{@id}")}
              phx-key="escape"
              phx-click-away={JS.exec("data-cancel", to: "##{@id}")}
    """
  end

We use JS.exec to execute the data-cancel attribute where we share the hide_modal command specified in phx-remove. We have the same behavior as before, but now it’s only sent a single time, instead of three times.

Happy coding!

–Chris

In this screencast, I show just how quickly we can add audio transcription to the open-source LiveBeats application we saw in a previous video. There’s no third-party APIs to call out to, no background jobs to kick off, and no JavaScript to write. The only external dependency is ffmpeg. Let’s go!

Happy coding!

–Chris

Note: To generate a new 1.7 project, you’ll need to install the phx.new generator from hex:

mix archive.install hex phx_new

Verified Routes

Verified routes replace router helpers with a sigil-based (~p), compile-time verified approach.

note: Verified routes make use of new Elixir 1.14 compiler features. Phoenix still supports older Elixir versions, but you’ll need to update to enjoy the new compile-time verification features.

In practice this means where before you used autogenerated functions like:

  # router
  get "/oauth/callbacks/:id", OAuthCallbackController, :new

  # usage
  MyRouter.Helpers.o_auth_callback_path(conn, :new, "github")
  # => "/oauth/callbacks/github"

  MyRouter.Helpers.o_auth_callback_url(conn, :new, "github")
  # => "http://localhost:4000/oauth/callbacks/github"

You can now do:

  # router
  get "/oauth/callbacks/:id", OAuthCallbackController, :new

  # usage
  ~p"/oauth/callbacks/github"
  # => "/oauth/callbacks/github"

  url(~p"/oauth/callbacks/github")
  # => "http://localhost:4000/oauth/callbacks/github"

This has a number of advantages. There’s no longer guesswork on which function was inflected – is it Helpers.oauth_callback_path or o_auth_callback_path, etc. You also no longer need to include the %Plug.Conn{}, or %Phoenix.Socket{}, or endpoint module everywhere when 99% of the time you know which endpoint configuration should be used.

There is also now a 1:1 mapping between the routes you write in the router, and how you call them with ~p. You simply write it as if you’re hard-coding strings everywhere in your app – except you don’t have maintenance issues that come with hardcoding strings. We can get the best of both worlds with ease of use and maintenance because ~p is a compile-time verified against the routes in your router.

For example, imagine we typo a route:

<.link href={~p"/userz/profile"}>Profile</.link>

The compiler will dispatch all ~p‘s at compile-time against your router, and let you know when it can’t find a matching route:

    warning: no route path for AppWeb.Router matches "/postz/#{post}"
      lib/app_web/live/post_live.ex:100: AppWeb.PostLive.render/1

Dynamic “named params” are also simply interpolated like a regular string, instead of arbitrary function arguments:

~p"/posts/#{post.id}"

Additionally, interpolated ~p values are encoded via the Phoenix.Param protocol. For example, a %Post{} struct in your application may derive the Phoenix.Param protocol to generate slug-based paths rather than ID based ones. This allows you to use ~p"/posts/#{post}" rather than ~p"/posts/#{post.slug}" throughout your application.

Query strings are also supported in verified routes, either in traditional query string form:

~p"/posts?page=#{page}"

Or as a keyword list or map of values:

params = %{page: 1, direction: "asc"}
~p"/posts?#{params}"

Like path segments, query strings params are proper URL encoded and may be interpolated directly into the ~p string.

Once you try out the new feature, you won’t be able to go back to router helpers. The new phx.gen.html|live|json|auth generators use verified routes.

Component-based Tailwind generators

Phoenix 1.7 ships with TailwindCSS by default, with no dependency on nodejs on the system. TailwindCSS is the best way I’ve found to style interfaces in my 20 years of web development. Its utility-first approach is far more maintainable and productive than any CSS system or framework I’ve used. It’s collocated approach also aligns perfectly within the function component and LiveView landscape.

The Tailwind team also generously designed the new project landing page, CRUD pages, and authentication system pages for new projects, giving you a first-class and polished starting point for building out your apps.

A new phx.new project will contain a CoreComponents module, housing a core set of UI components like tables, modals, forms, and data lists. The suite of Phoenix generators (phx.gen.html|live|json|auth) make use of the core components. This has a number of neat advantages.

First, you can customize your core UI components to suit whatever needs, designs, and tastes that you have. If you want to use Bulma or Bootstrap instead of Tailwind – no problem! Simply replace the function definitions in core_components.ex with your framework/UI specific implementations and the generators continue to provide a great starting point for new features whether you’re a beginner, or seasoned expert building bespoke product features.

In practice, the generators give you templates that make use of your core components, which look like this:

<.header>
  New Post
  <:subtitle>Use this form to manage post records in your database.</:subtitle>
</.header>

<.simple_form for={@form} action={~p"/posts"}>
  <input field={@form[:title]} type="text" label="Title" />
  <input field={@form[:views]} type="number" label="Views" />

  <:actions>
    <.button>Save Post</.button>
  </:actions>
</.simple_form>

<.back navigate={~p"/posts"}>Back to posts></.back>

We love what the Tailwind team designed for new applications, but we also can’t wait to see the community release their own drop-in replacements for core_components.ex for various frameworks of choice.

Unified function components across Controllers and LiveViews

Function components provided by HEEx, with declarative assigns and slots, are massive step-change in the way we write HTML in Phoenix projects. Function components provide UI building blocks, allowing features to be encapsulated and better extended over the previous template approach in Phoenix.View. You get a more natural way to write dynamic markup, reusable UI that can be extended by the caller, and compile-time features to make writing HTML-based applications a truly first-class experience.

Function components bring a new way to write HTML applications in Phoenix, with new sets of conventions. Additionally, users have struggled with how to marry controller-based Phoenix.View features with Phoenix.LiveView features in their applications. Users found themselves writing render("table", user: user) in controller-based templates, while their LiveViews made use of the new <.table rows={@users}> features. There was no great way to share the approaches in an application.

For these reasons, the Phoenix team unified the HTML rendering approaches whether from a controller request, or a LiveView. This shift also allowed us to revisit conventions and align with the LiveView approach of collocating templates and app code together.

New applications (and the phx generators), remove Phoenix.View as a dependency in favor of a new Phoenix.Template dependency, which uses function components as the basis for all rendering in the framework.

Your controllers still look the same:

defmodule AppWeb.UserController do
  use MyAppWeb, :controller

  def index(conn, _params) do
    users = ...
    render(conn, :index, users: users)
  end
end

But instead of the controller calling AppWeb.UserView.render("index.html", assigns), we’ll now first look for an index/1 function component on the view module, and call that for rendering if it exists. Additionally, we also renamed the inflected view module to look for AppWeb.UserHTML, or AppWeb.UserJSON, and so on for a view-per-format approach for rendering templates. This is all done in backwards compatible way, and is opt-in based on options to use Phoenix.Controller.

All HTML rendering is then based on function components, which can be written directly in a module, or embedded from an external file with the new embed_templates macro provided by Phoenix.Component. Your PageHTML module in a new application looks like this:

defmodule AppWeb.PageHTML do
  use AppWeb, :html

  embed_templates "page_html/*"
end

The new directory structure will look something like this:

lib/app_wb
├── controllers
│   ├── page_controller.ex
│   ├── page_html.ex
│   ├── error_html.ex
│   ├── error_json.ex
│   └── page_html
│       └── home.html.heex
├── live
│   ├── home_live.ex
├── components
│   ├── core_components.ex
│   ├── layouts.ex
│   └── layouts
│       ├── app.html.heex
│       └── root.html.heex
├── endpoint.ex
└── router.ex

Your controllers-based rendering or LiveView-based rendering now all share the same function components and layouts. Whether running phx.gen.html, phx.gen.live, or phx.gen.auth, the new generated templates all make use of your components/core_components.ex definitions.

Additionally, we have collocated the view modules next to their controller files. This brings the same benefits of LiveView collocation – highly coupled files live together. Files that must change together now live together, whether writing LiveView or controller features.

These changes were all about a better way to write HTML-based applications, but they also simplified rendering other formats, like JSON. For example, JSON based view modules follow the same conventions – Phoenix will first look for an index/1 function when rendering the index template, before trying render/2. This allowed us to simplify JSON rendering in general and do away with concepts like Phoenix.View.render_one|render_many.

For example, this is a JSON view generated by phx.gen.json:

defmodule AppWeb.PostJSON do
  alias AppWeb.Blog.Post

  @doc """
  Renders a list of posts.
  """
  def index(%{posts: posts}) do
    %{data: for(post <- posts, do: data(post))}
  end

  @doc """
  Renders a single post.
  """
  def show(%{post: post}) do
    %{data: data(post)}
  end

  defp data(%Post{} = post) do
    %{
      id: post.id,
      title: post.title
    }
  end
end

Notice how it’s all simply regular Elixir functions – as it should be!

These features provide a unified rendering model for applications going forward with a new and improved way to write UIs, but they are a deviation from previous practices. Most large, established applications are probably best served by continuing to depend on Phoenix.View.

LiveView Streams

LiveView now includes a streaming interface for managing large collections in the UI without having to store the collections in memory on the server. With a couple function calls you can insert new items into the UI, append or prepend dynamically, or re-order items without reloading the items on the server.

The phx.gen.live live CRUD generator in Phoenix 1.7 uses streams to manage the your list of items. This allows data entry, updates, and deletes without ever needing to refetch the list of items after the initial load. Let’s see how.

The following PostLive.Index module is generated when you run mix phx.gen.live Blog Post posts title views:integer

defmodule DemoWeb.PostLive.Index do
  use DemoWeb, :live_view

  alias Demo.Blog
  alias Demo.Blog.Post

  @impl true
  def mount(_params, _session, socket) do
    {:ok, stream(socket, :posts, Blog.list_posts())}
  end

  ...
end

Notice how instead of the regular assign(socket, :posts, Blog.list_posts()), we have a new stream/3 interface. This sets up the stream with the initial collection of posts. Then in the generated index.html.heex template, we consume the stream to render the posts table:

<.table
  id="posts"
  rows={@streams.posts}
  row_click={fn {_id, post} -> JS.navigate(~p"/posts/#{post}") end}
>
  <:col :let={{_id, post}} label="Title"><%= post.title %></:col>
  <:col :let={{_id, post}} label="Views"><%= post.views %></:col>
  <:action :let={{_id, post}}>
    <div class="sr-only">
      <.link navigate={~p"/posts/#{post}"}>Show</.link>
    </div>
    <.link patch={~p"/posts/#{post}/edit"}>Edit</.link>
  </:action>
  <:action :let={{id, post}}>
    <.link
      phx-click={JS.push("delete", value: %{id: post.id}) |> hide("##{id}")}
      data-confirm="Are you sure?"
    >
      Delete
    </.link>
  </:action>
</.table>

This looks very similar to the old template, but instead of accessing the bare @posts assign, we pass the @stream.posts to our table. When consuming a stream we also are passed the stream’s DOM id, along with the item.

Back on the server, we can see how simple it is to insert new items into the table. When our generated FormComponent updates or saves a post via the form, we send a message pack to the parent PostLive.Index LiveView about the new or updated post:

PostLive.FormComponent:

defmodule DemoWeb.PostLive.FormComponent do
  ...
  defp save_post(socket, :new, post_params) do
    case Blog.create_post(post_params) do
      {:ok, post} ->
        notify_parent({:saved, post})

        {:noreply,
         socket
         |> put_flash(:info, "Post created successfully")
         |> push_patch(to: socket.assigns.patch)}

      {:error, %Ecto.Changeset{} = changeset} ->
        {:noreply, assign_form(socket, changeset)}
    end
  end

  defp notify_parent(msg), do: send(self(), {__MODULE__, msg})
end

Then we pick the message up in a PostLive.Index handle_info clause:

@impl true
def handle_info({DemoWeb.PostLive.FormComponent, {:saved, post}}, socket) do
  {:noreply, stream_insert(socket, :posts, post)}
end

So the form tells us it saved a post, and we simply stream_insert the post in our stream. That’s it! If a post already exists in the UI, it will be updated in place. Otherwise it is appended to the container by default. You can also prepend with stream_insert(socket, :posts, post, at: 0), or pass any index to :at for arbitrary item insertion or re-ordering.

Streams were one of the final building blocks on our way to LiveView 1.0 and I’m super happy where we landed.

New Form field datastructure

We’re all familiar with the Phoenix.HTML form primitives of <.form for={@changeset}>, where the form takes a datastructure that implements the Phoenix.HTML.FormData protocol and returns a %Phoenix.HTML.Form{}. One issue our approach had is the form datastructure couldn’t track individual form field changes. This made optimizations impossible in LiveView where we’d have to re-render and resend the form on any individual change. With the introduction of Phoenix.HTML.FormData.to_form and Phoenix.Component.to_form, we now have a %Phoenix.HTML.FormField{} datastructue for individual field changes.

The new phx.gen.live generators and your core_components.ex take advantage of these new additions.

What’s Next for Phoenix and LiveView

The Phoenix generators make use of LiveViews latest features, and that will continue to expand. With streaming collections as the default, we can move towards more advanced out-of-the-box features for our live CRUD generators in phx.gen.live. For example, we plan to introduce synced UIs out-of-the-box for resources. The generated Phoenix form features will continue to evolve with the addition of new the to_form interface.

For LiveView, to_form allowed us to ship the basis of optimized forms. Now an individual change to one form field will produce an optimized diff.

Following this optimization work, the major remaining feature for LiveView 1.0 is an expanded form API that better supports dynamic forms inputs, wizard-style forms, and delegating form inputs to child LiveComponents.

Alternative Webserver Support

Thanks to work by Mat Trudel, we now have the basis for first-class webserver support in Plug and Phoenix, allowing other webservers like Bandit to be swapped in Phoenix while enjoying all features like WebSockets, Channels, and LiveView. Stay tuned to the Bandit project if you’re interested in a pure Elixir HTTP server or give it a try in your own Phoenix projects!

What’s Next

As always, step-by-step upgrade guides are there to take your existing 1.6.x apps up to 1.7.

The full changelog can be found here.

Find us on elixir slack or the forums if you have issues.

Happy coding!

–Chris

Note: For the rc period, you’ll need to explicitly install the phx.new generator from hex to try out a fresh project:

mix archive.install hex phx_new 1.7.0-rc.0

Verified Routes

Verified routes replace router helpers with a sigil-based (~p), compile-time verified approach.

note: Verified routes make use of new Elixir 1.14 compiler features. Phoenix still supports older Elixir versions, but you’ll need to update to enjoy the new compile-time verification features.

In practice this means where before you used autogenerated functions like:

  # router
  get "/oauth/callbacks/:id", OAuthCallbackController, :new

  # usage
  MyRouter.Helpers.o_auth_callback_path(conn, :new, "github")
  # => "/oauth/callbacks/github"

  MyRouter.Helpers.o_auth_callback_url(conn, :new, "github")
  # => "http://localhost:4000/oauth/callbacks/github"

You can now do:

  # router
  get "/oauth/callbacks/:id", OAuthCallbackController, :new

  # usage
  ~p"/oauth/callbacks/github"
  # => "/oauth/callbacks/github"

  url(~p"/oauth/callbacks/github")
  # => "http://localhost:4000/oauth/callbacks/github"

This has a number of advantages. There’s no longer guesswork on which function was inflected – is it Helpers.oauth_callback_path or o_auth_callback_path, etc. You also no longer need to include the %Plug.Conn{}, or %Phoenix.Socket{}, or endpoint module everywhere when 99% of the time you know which endpoint configuration should be used.

There is also now a 1:1 mapping between the routes you write in the router, and how you call them with ~p. You simply write it as if you’re hard-coding strings everywhere in your app – except you don’t have maintenance issues that come with hardcoding strings. We can get the best of both worlds with ease of use and maintenance because ~p is a compile-time verified against the routes in your router.

For example, imagine we typo a route:

<.link href={~p"/userz/profile"}>Profile</.link>

The compiler will dispatch all ~p‘s at compile-time against your router, and let you know when it can’t find a matching route:

    warning: no route path for AppWeb.Router matches "/postz/#{post}"
      lib/app_web/live/post_live.ex:100: AppWeb.PostLive.render/1

Dynamic “named params” are also simply interpolated like a regular string, instead of arbitrary function arguments:

~p"/posts/#{post.id}"

Additionally, interpolated ~p values are encoded via the Phoenix.Param protocol. For example, a %Post{} struct in your application may derive the Phoenix.Param protocol to generate slug-based paths rather than ID based ones. This allows you to use ~p"/posts/#{post}" rather than ~p"/posts/#{post.slug}" throughout your application.

Query strings are also supported in verified routes, either in traditional query string form:

~p"/posts?page=#{page}"

Or as a keyword list or map of values:

params = %{page: 1, direction: "asc"}
~p"/posts?#{params}"

Like path segments, query strings params are proper URL encoded and may be interpolated directly into the ~p string.

Once you try out the new feature, you won’t be able to go back to router helpers. The new phx.gen.html|live|json|auth generators use verified routes.

Component-based Tailwind generators

Phoenix 1.7 ships with TailwindCSS by default, with no dependency on nodejs on the system. TailwindCSS is the best way I’ve found to style interfaces in my 20 years of web development. Its utility-first approach is far more maintainable and productive than any CSS system or framework I’ve used. It’s collocated approach also aligns perfectly within the fucntion component and LiveView landscape.

The Tailwind team also generously designed the new project landing page, CRUD pages, and authentication system pages for new projects, giving you a first-class and polished starting point for building out your apps.

A new phx.new project will contain a CoreComponents module, housing a core set of UI components like tables, modals, forms, and data lists. The suite of Phoenix generators (phx.gen.html|live|json|auth) make use of the core components. This has a number of neat advantages.

First, you can customize your core UI components to suit whatever needs, designs, and tastes that you have. If you want to use Bulma or Bootstrap instead of Tailwind – no problem! Simply replace the function definitions in core_components.ex with your framework/UI specific implementations and the generators continue to provide a great starting point for new features whether you’re a beginner, or seasoned expert building bespoke product features.

In practice, the generators give you templates that make use of your core components, which look like this:

<.header>
  New Post
  <:subtitle>Use this form to manage post records in your database.</:subtitle>
</.header>

<.simple_form :let={f} for={@changeset} action={~p"/posts"}>
  <.error :if={@changeset.action}>
    Oops, something went wrong! Please check the errors below.
  </.error>

  <input field={{f, :title}} type="text" label="Title" />
  <input field={{f, :views}} type="number" label="Views" />

  <:actions>
    <.button>Save Post</.button>
  </:actions>
</.simple_form>

<.back navigate={~p"/posts"}>Back to posts></.back>

We love what the Tailwind team designed for new applications, but we also can’t wait to see the community release their own drop-in replacements for core_components.ex for various frameworks of choice.

Unified function components across Controllers and LiveViews

Function components provided by HEEx, with declarative assigns and slots, are massive step-change in the way we write HTML in Phoenix projects. Function components provide UI building blocks, allowing features to be encapsulated and better extended over the previous template approach in Phoenix.View. You get a more natural way to write dynamic markup, reusable UI that can be extended by the caller, and compile-time features to make writing HTML-based applications a truly first-class experience.

Function components bring a new way to write HTML applications in Phoenix, with new sets of conventions. Additionally, users have struggled with how to marry controller-based Phoenix.View features with Phoenix.LiveView features in their applications. Users found themselves writing render("table", user: user) in controller-based templates, while their LiveViews made use of the new <.table rows={@users}> features. There was no great way to share the approaches in an application.

For these reasons, the Phoenix team unified the HTML rendering approaches whether from a controller request, or a LiveView. This shift also allowed us to revisit conventions and align with the LiveView approach of collocating templates and app code together.

New applications (and the phx generators), remove Phoenix.View as a dependency in favor of a new Phoenix.Template dependency, which uses function components as the basis for all rendering in the framework.

Your controllers still look the same:

defmodule AppWeb.UserController do
  use MyAppWeb, :controller

  def index(conn, _params) do
    users = ...
    render(conn, :index, users: users)
  end
end

But instead of the controller calling AppWeb.UserView.render("index.html", assigns), we’ll now first look for an index/1 function component on the view module, and call that for rendering if it exists. Additionally, we also renamed the inflected view module to look for AppWeb.UserHTML, or AppWeb.UserJSON, and so on for a view-per-format approach for rendering templates. This is all done in backwards compatible way, and is opt-in based on options to use Phoenix.Controller.

All HTML rendering is then based on function components, which can be written directly in a module, or embedded from an external file with the new embed_templates macro provided by Phoenix.Component. Your PageHTML module in a new application looks like this:

defmodule AppWeb.PageHTML do
  use AppWeb, :html

  embed_templates "page_html/*"
end

The new directory structure will look something like this:

lib/app_wb
├── controllers
│   ├── page_controller.ex
│   ├── page_html.ex
│   ├── error_html.ex
│   ├── error_json.ex
│   └── page_html
│       └── home.html.heex
├── live
│   ├── home_live.ex
├── components
│   ├── core_components.ex
│   ├── layouts.ex
│   └── layouts
│       ├── app.html.heex
│       └── root.html.heex
├── endpoint.ex
└── router.ex

Your controllers-based rendering or LiveView-based rendering now all share the same function components and layouts. Whether running phx.gen.html, phx.gen.live, or phx.gen.auth, the new generated templates all make use of your components/core_components.ex definitions.

Additionally, we have collocated the view modules next to their controller files. This brings the same benefits of LiveView collocation – highly coupled files live together. Files that must change together now live together, whether writing LiveView or controller features.

These changes were all about a better way to write HTML-based applications, but they also simplified rendering other formats, like JSON. For example, JSON based view modules follow the same conventions – Phoenix will first look for an index/1 function when rendering the index template, before trying render/2. This allowed us to simplify JSON rendering in general and do away with concepts like Phoenix.View.render_one|render_many.

For example, this is a JSON view generated by phx.gen.json:

defmodule AppWeb.PostJSON do
  alias AppWeb.Blog.Post

  @doc """
  Renders a list of posts.
  """
  def index(%{posts: posts}) do
    %{data: for(post <- posts, do: data(post))}
  end

  @doc """
  Renders a single post.
  """
  def show(%{post: post}) do
    %{data: data(post)}
  end

  defp data(%Post{} = post) do
    %{
      id: post.id,
      title: post.title
    }
  end
end

Notice how it’s all simply regular Elixir functions – as it should be!

These features provide a unified rendering model for applications going forward with a new and improved way to write UIs, but they are a deviation from previous practices. Most large, established applications are probably best served by continuing to depend on Phoenix.View.

Alternative Webserver Support

Thanks to work by Mat Trudel, we now have the basis for first-class webserver support in Plug and Phoenix, allowing other webservers like Bandit to be swapped in Phoenix while enjoying all features like WebSockets, Channels, and LiveView. Stay tuned to the Bandit project if you’re interested in a pure Elixir HTTP server or give it a try in your own Phoenix projects!

As always, step-by-step upgrade guides are there to take your existing 1.6.x apps up to 1.7.

The full changelog can be found here.

Find us on elixir slack or the forums if you have issues.

Happy coding!

–Chris

Additionally, new out-of-the-box focus components and JS commands provide accessibility improvements to ensure LiveView applications work well for all users. We also shipped a new mix formatter plugin for formatting HEEx templates, which is something you can’t live without after using it.

To understand why these features are a such a big deal, let’s take a look at a simple function component. Let’s say we have a modal component in our application and we want to call it. Prior to function components, you would write your Elixir template like this:

<div>
  <%= modal(title: "Your file is ready!") do %>
    The file will only be available for 10 minutes
  <% end %>
</div>

This is simple enough, but the issue comes when we want to place arbitrary content inside our modal title, such as a link to the download. We end up trying to concat raw HTML string together and it’s a nonstarter:

<div>
  <%= modal(title: "Your #{"<a href=\"#{@url}\" download>file</a>"} is ready!") do %>
    The file will only be available for 10 minutes
  <% end %>
</div>

This fails because Phoenix performs HTML escaping on strings, so we’d need to carefully unpack our own HTML input. The standard template model breaks down in terms of composability. Function components and slots solve this issue by allowing components to declare named slots where the caller can provide arbitrary content to named sections such as a modal title, header, or footer. Let’s rewrite the above with a function component and slot:

<div>
  <.modal>
    <:title>
      Your <.link href={@url} download>file</.link> is ready!
    </:title>
    The file will only be available for 10 minutes
  </.modal>
</div>

Now we can start to see the real power of function components and slots. Function components compose nicely within markup, and slots allow the caller to provide their own arbitrary structure, like the <:title> slot above. Here we are passing our own markup content, including calls to other function components! This allows encapsulated UI building blocks that compose together. No more arbitrary string concatenation or bespoke strict templates for each and every usecase.

Slots provide even more powerful composition. Instead of placing a single named thing in a component, slots are collections, which allows the caller to provide an arbitrary number of slot entries to a component. For example, imagine a table component where the caller needs to provide an arbitrary number of table columns. This is impossible to compose cleanly with common static HTML template abstractions, but with slots it’s beautiful to read and write:

<.table id="files" rows={@files}>
  <:col :let={file} label="Name"><%= file.name %></:col>
  <:col :let={file} label="Size"><%= file.size %></:col>
  <:action :let={file}>
    <.link patch={~p"/files/#{file}/edit"}>Edit</.link>
  </:action>
  <:action :let={file}>
    <.link phx-click={JS.push("delete", value: %{id: file.id})} data-confirm="Are you sure?">
      Delete
    </.link>
  </:action>
</.table>

Rather than writing raw <table> tags everywhere or bespoke functions like <%= file_table(rows: @files)>, we can leverage slots to define a single <.table> function component in our application which accepts a <:col> and <:action> slot. Notice how we passed multiple columns and actions above? This is a beautiful feature of slots. Internally the table can render the <thead> and <th> entries based on each <:col> label we provided. Next, to render each row, the component simply iterates over each of the rows we passed and renders a column and inner content based on each of our <:col>‘s. This makes writing markup far more pleasant and reusable compared to writing raw HTML and copy pasting styles and tags around. You’ll find once you have a core set of UI components established in your application, you rarely need to extend them with new features because of component and slot composition.

This is all looking really nice, but with more attributes and slots that are added over time, how do we discover what’s actually supported? How confident can we be with consuming such components? Enter declarative assigns and slots, where the compiler has your back.

Declarative Assigns and Slots

Thanks to Marlus Saraiva’s work trailblazing these features in the Surface library, and then contributing them to LiveView, components have now been taken to the next-level of usability and productivity.

To see how, let’s head back over to our modal. Let’s say we way to automatically show the modal when it is rendered on page load vs programmatically showing it later. Assuming someone on the team decently documented the function, we could go spelunking and maybe find an example with the show attribute to auto-show the modal. But even the best documentation can’t save us from typos or incorrect attributes or slots. For example, imagine we incorrectly pass <.modal autoshow>:

Fortunately, the compiler has our back! Here we see that our autoshow is an unknown attribute, and we learn we left off the required id attribute. We get this feedback in real-time in our editor rather than waiting for an error to pop up at runtime.

With declarative assigns and slots, function components specify the attributes, types, and slots they accept along with inline documentation. This not only provides enhanced docs, but each call of the component will be compile-time verified to provide feedback. No more runtime footguns or guesswork. This also allows the community to release first-class UI libraries where users can hit the ground running while building out their applications. Here’s what it looks like in practice:

HEEx HTML Formatter

Thanks to fantastic work by Feelipe Renan, your .heex files and any ~H template in the app will now be HTML formatted when running mix format. This is especially helpful because your markup and function components have embedded Elixir expressions, and you want those expressions formatted with regular rules like any other Elixir code. The HEEx formatter handles all those cases – formatting generic markup, formatting Elixir expressions within tags, and formatting your Elixir expressions within EEx content <%= %>. The formatter also makes sure both front-end and backend developers follow a unified coding guideline across their applications.

Let’s see it in action:

Accessibility

LiveView should be a fantastic web experience for all users, including those with accessibility needs such as screen reader users. LiveView 0.18 includes a few primitives to help on this front, with more coming soon.

First, we shipped a new <.focus_wrap> component that allows you to simply wrap any template content in <.focus_wrap>...</.focus_wrap> to have tab focus wrap back around the element. This may not sound exciting, but for screen reader users navigating with the keyboard, it is an essential primitive when displaying dialogs and modals. It’s also a feature that otherwise requires developer intervention with custom JavaScript. Let’s see it in action:

We also shipped new JS commands for handling focus states, including JS.focus and JS.focus_first. Both allow you to programmatically set the focus on an element, but JS.focus_first is especially nice as a set-and-forget command that does the right thing from an accessibility perspective. It simply finds the first focusable element within a container and sets focus there, without you having to think about it. For example, when popping a modal, you don’t need to consider if the modal has form inputs in one case, or only confirm/cancel buttons in another. Simply use the command to find the first thing to focus on and LiveView will place focus there.

Your show modal function might look something like this:

def show_modal(js \\ %JS{}, id) when is_binary(id) do
  js
  |> JS.show(to: "##{id}")
  |> JS.show(to: "##{id}-bg")
  |> show("##{id}-container")
  |> JS.focus_first(to: "##{id}-container")
end

Now any place that shows a modal in the app will focus within that modal. Coupled with <.focus_wrap> and the aria labels that phx.new will generate, screen readers users will have a fully accessible modal out of the box when using your application.

JS commands and hooks in dead views

JS commands are another declarative LiveView feature that allows you to manipulate the DOM on the client without a trip to the server. They are especially useful for showing modals and dropdowns, dispatching events, animating content, and toggling attributes, but so far have been a LiveView specific feature. Regular static views also share these same use-cases where folks want to show or hide content without bespoke JavaScript or brining in frameworks. LiveView 0.18 now includes support for JS commands and hooks inside content rendered outside of LiveView. This allows many of your core UI function components to be used across LiveViews or regular views, such as modals, flash messages, and dropdowns.

We are super excited about this release and the productivity improvements it brings, and we can’t wait to show off all the neat things it enables with upcoming Phoenix 1.7 applications.

Stay tuned and happy coding!

–Chris

mix archive.install hex phx_new 1.6.0

New authentication and mailer generators

Thanks to efforts by José Valim and Aaron Renner, Phoenix 1.6 ships with a new phx.gen.auth command for a complete authentication solution bootstrapped into your application. You can read about the design decisions behind the authentication generators in José’s post on the Dashbit blog. Phoenix also now includes swoosh by default for mailer support and a new phx.gen.notifier task for generating a notifier for sending email along with a dev mailbox for local development.

New LiveView HEEx engine

In addition to the generators, Phoenix LiveView 0.16 was just released with a new HTML engine (HEEx, ~H) for HTML-aware template compilation which you’ll see utilized in all phoenix generated HTML files going forward (phx.new, phx.gen.html, phx.gen.live, etc). The new engine not only enforces proper HTML, but provides syntax conveniences for rendering components, such as <.form for={@user} id="user-form">. This new engine is thanks to Marlus Saraiva’s excellent work that he extracted from his wonderful Surface library, which builds features on top of Phoenix LiveView. We look forward to seeing where each project can continue to innovate and share back as we work towards new engine features. With the HTML engine and function components in place, we have the layed the groundwork for a vibrant ecosystem of shared and resuable components. You can follow along the HEEx roadmap to stay up to date on our feature plans. For now, here’s a quick rundown on HEEx from the Phoenix LiveView docs to bring folks up to speed:

Note: HEEx requires Elixir >= 1.12.0 in order to provide accurate file:line:column information in error messages. Earlier Elixir versions will work but will show inaccurate error messages.

HEEx is a HTML-aware and component-friendly extension of EEx that provides:

• Built-in handling of HTML attributes
• An HTML-like notation for injecting function components
• Compile-time validation of the structure of the template
• The ability to minimize the amount of data sent over the wire

Example

~H"""
<div title="My div" class={@class}>
  <p>Hello <%= @name %></p>
  <MyApp.Weather.city name="Kraków"/>
</div>
"""

Syntax

HEEx is built on top of Embedded Elixir (EEx), a templating syntax that uses <%= ... %> for interpolating results. In this section, we are going to cover the basic constructs in HEEx templates as well as its syntax extensions.

Interpolation

Both HEEx and EEx templates use <%= ... %> for interpolating code inside the body of HTML tags:

<p>Hello, <%= @name %></p>

Similarly, conditionals and other block Elixir constructs are supported:

<%= if @show_greeting? do %>
  <p>Hello, <%= @name %></p>
<% end %>

Note we don’t include the equal sign = in the closing tag (because the closing tag does not output anything).

There is one important difference between HEEx and Elixir’s builtin EEx. HEEx uses a specific annotation for interpolating HTML tags and attributes. Let’s check it out.

HEEx extension: Defining attributes

Since HEEx must parse and validate the HTML structure, code interpolation using <%= ... %> and <% ... %> are restricted to the body (inner content) of the HTML/component nodes and it cannot be applied within tags.

For instance, the following syntax is invalid:

<div class="<%= @class %>">
  ...
</div>

Instead do:

<div class={@class}>
  ...
</div>

For multiple dynamic attributes, you can use the same notation but without assigning the expression to any specific attribute.

<div {@dynamic_attrs}>
  ...
</div>

The expression inside { ... } must be either a keyword list or a map containing the key-value pairs representing the dynamic attributes.

HEEx extension: Defining function components

Function components are stateless components implemented as pure functions with the help of the Phoenix.Component module. They can be either local (same module) or remote (external module).

HEEx allows invoking whose function components directly in the template using an HTML-like notation. For example, a remote function:

<MyApp.Weather.city name="Kraków"/>

A local function can be invoked with a leading dot:

<.city name="Kraków"/>

where the component could be defined as follows:

defmodule MyApp.Weather do
  use Phoenix.Component

  def city(assigns) do
    ~H"""
    The chosen city is: <%= @city %>.
    """
  end

  def country(assigns) do
    ~H"""
    The chosen country is: <%= @country %>.
    """
  end
end

It is typically best to group related functions into a single module, as opposed to having many modules with a single render/1 function. You can learn more about components in Phoenix.Component.

New LiveView server lifecycle hooks

Thanks to work by Michael Crumm on the Phoenix team, LiveView 0.16 introduces on_mount and attach_hook hooks which provide a mechanism to tap into key stages of the LiveView lifecycle. This allows developers to bind/update assigns, intercept events, patches, and regular messages when necessary, and to inject common functionality. Hooks may be attached to any of the following lifecycle stages: :mount (via on_mount/1), :handle_params, :handle_event, and :handle_info.

New LiveView live_session for optimized navigation

LiveView 0.16 also introduces the live_session macro in the router to group live routes together. This allows all live navigation through live redirects to happen over the existing websocket connection. This avoids an extra HTTP round trip to the server and provides an extremely fast navigation experience because an HTTP handshake is no longer necessary at all. The live_session also allows a life-cycle on_mount hook to be provided, allowing LiveViews to share common code paths such as authentication without needing to specificy the hooks on every module.

Node and webpack free asset building with esbuild

In addition to the new HTML engine, we’ve also had a major change on the way the phx.new project generators handles assets. We have dropped webpack and node entirely from the equation. You can now build your js and css bundles without having node or npm on your system! The biggest support issues for Phoenix over the years has revolved around node tooling, breaking changes, and often times unnecessary churn. By using esbuild, projects can utilize a portable binary for multiplatform, dependency-free asset building that is fast and Just Works/tm. Five years from now you shouldn’t been afraid to make some changes to a js or css file and find your tooling has broken underneath you. Advanced front-end users can continue to take advantage of the webpack tooling that suits their work-flows, but we hope this dependency-free solution brings more “peace of mind” around assets, per the Phoenix tagline :). Big thanks to Brian Cardarella of DockYard and Max Veytsman on the Phoenix team for spelunking through our js options and experimenting with solutions, along with Wojtek Mach for heading up the portable binary esbuild extraction. Also shout out to José for writing some go and JavaScript PRs for various tools to handle mix shutdown without zombie processes.

This release also extracts Phoenix.View into its own library phoenix_view, so non-web users can make use of Phoenix’s view rendering without bringing in all of Phoenix.

As always, step-by-step upgrade guides can be found here:

https://gist.github.com/chrismccord/2ab350f154235ad4a4d0f4de6decba7b

You can also view the full changelog for more details.

Find us on elixir slack or the forums if you need help. Happy coding!

–Chris

Phoenix’s test suites

Phoenix has 4 different test suites, each with different purposes and different dependencies.

How we test locally

The ability to download a project and easily run its test suite locally, is key to welcoming community contributions. Phoenix uses ExUnit which comes with Elixir, so running the main test suite couldn’t be easier:

> mix test
....
Finished in 24.8 seconds
11 doctests, 737 tests, 0 failures

The installer test suite is equally easy to run… it’s just mix test in the /installer folder

Things start to get more complex, however, when we start making changes to the code generators. Although we can ensure our generators create files in the correct location, we don’t actually know the generated code works until we try to run it. For this reason, Phoenix has an integration testing suite in /integration_test:

> tree
├── config
│   └── config.exs
├── docker-compose.yml
├── mix.exs
├── mix.lock
└── test
    ├── code_generation
    │   ├── app_with_defaults_test.exs
    │   ├── app_with_mssql_adapter_test.exs
    │   ├── app_with_mysql_adapter_test.exs
    │   ├── app_with_no_options_test.exs
    │   └── umbrella_app_with_defaults_test.exs
    ├── support
    │   └── code_generator_case.ex
    └── test_helper.exs

To run these tests fully we need access to three separate databases: Postgres, MySQL and MSSQL. This would normally be difficult, but fortunately Phoenix has a docker-compose file:

version: '3'
services:
  postgres:
    image: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: postgres
  mysql:
    image: mysql
    ports:
      - "3306:3306"
    environment:
      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
  mssql:
    image: mcr.microsoft.com/mssql/server:2019-latest
    environment:
      ACCEPT_EULA: Y
      SA_PASSWORD: some!Password
    ports:
      - "1433:1433"

This allows us to start up these databases and run the integration tests like this:

> docker-compose up -d
Starting integration_test_postgres_1 ... done
Starting integration_test_mssql_1    ... done
Starting integration_test_mysql_1    ... done
> mix test --include database
    Finished in 230.6 seconds
    32 tests, 0 failures
    Randomized with seed 896813

How we tested in CI

The Phoenix project uses GitHub Actions (GHA) to run each of its test suites. Like most CI services, GitHub depends on its own specific configuration file to install build dependencies, start external services, and execute the various test suites.

Since Phoenix’s CI and local test environments use different tools, we ended up with duplicate configurations and different environments for the same tests. Duplicate configurations caused issues when things went out of sync. Different environments meant we did not have complete faith that our tests would behave the same on GitHub when compared to our local machines. And when things worked locally but not in CI, it was an incredibly time consuming process to push test commits to Github with debugging statements to try to figure out the cause of the problem.

What if I could run the CI build my local machine?

Around this time José was talking with Vlad about the inconsistencies between local development and CI. Vlad proposed we try Earthly, an open source format for specifying builds that he created.

Vlad’s insight is that if we were to define the whole build process, unit tests, integration tests, service setup and so on, in a format that could be run anywhere, then reproducing builds failures would be easy.

Following this approach, our build would look something like this:

Earthfile

FROM hexpm/elixir:1.11-erlang-21.0-alpine-3.12.0
all:
    BUILD +test
    BUILD +integration-test
test:
    WORKDIR /src/
    COPY . .
    RUN mix test
integration-test:
    WORKDIR /src/integration_test
    COPY . .
    RUN mix deps.get
    WITH DOCKER --compose docker-compose.yml
        RUN mix test --include database
    END

We could then run the various build targets, all, test or integration-test, locally or in GHA by calling earthly and specifying a target.

> earthly -P +all

Now, if an integration test fails in a GHA run, we could have confidence that we will be able to reproduce it locally by running the same command. The whole build is containerized, which makes reproducing things much easier. This would not only be great for reproducing build failures but could also be nice for working on the build process itself, without having to push and wait for GHA to run. Earthly even allows us to drop into a shell in the build pipeline to poke around and diagnose problems (more on that later). The Earthfile syntax builds on top of docker’s layers, so if our mix.lock file hasn’t changed, it will use the cached layer and not attempt to download our dependencies again. In a post COVID world, where we’re back to traveling again, we could even work on the build pipeline on a plane.

Testing multiple dependency versions

Phoenix’s build pipeline is more complex than running each test suite once, though. Each release of Phoenix needs to work with not just the latest version of Elixir, but all supported versions. The same for OTP. GHA has great support for this use case with a feature called “Matrix Strategy”. You define a matrix of parameters and it will execute your job using each of these.

  matrix:
    include:
      - elixir: 1.9.4
        otp: 20.3.8.26
      - elixir: 1.10.4
        otp: 21.3.8.17
      - elixir: 1.10.4
        otp: 23.0.3

The matrix strategy runs all these jobs in parallel, which means that testing many versions does not impact our build run time. It’s a key feature for a library like Phoenix. It does make the local reproducibility problem more difficult, however. If we’re running the latest supported version of OTP and a PR fails for one of the supported older OTP versions, we can attempt to switch versions or maybe just rely on the GHA build to test our changes. In practice there have been times where we end up relying on GHA, which means we now have a longer feedback cycle. Not the end of the world certainly, but again, it is a bit more friction added to the contribution process.

Reproducing Matrix Testing Locally

Again, using earthly can make this situation a little easier to deal with. We can introduce arguments for the elixir and OTP version and then use those to run tests with any version we please. No local environment changes or additional tooling.

The solution the Phoenix framework ended up with looks something like this:

setup:
   ARG ELIXIR=1.11
   ARG OTP=23.0.0
   FROM hexpm/elixir:$ELIXIR-erlang-$OTP-alpine-3.12.0
   ...

integration-test:
    FROM +setup
    COPY --dir assets config installer lib integration_test priv test ./
    WORKDIR /src/integration_test
    RUN mix deps.get
    WITH DOCKER --compose docker-compose.yml
        RUN mix test --include database
    END

This makes it really easy to test any version combination locally:

>  earthly -P --build-arg ELIXIR=1.11.0 --build-arg OTP=23.1.1 +integration-test
 +integration-test | Including tags: [:database]

  ...
   +integration-test | Finished in 210.5 seconds
   +integration-test | 32 tests, 0 failures

   +integration-test | Randomized with seed 330691
              output | --> exporting outputs
=========================== SUCCESS ===========================

This is really cool how low friction Earthly’s solution is. Also, Earthly has an –interactive flag, which pops us into a shell when a step in the build returns a non zero status.

Adopting Earthly

All of this said, I’m excited to announce that the Phoenix project’s CI pipeline is now powered by Earthly.

Adam Gordon Bell submitted the PR in early October and was awesome to work with as we went through the evaluation process. The final version is more complex than the examples found in this article and continues to evolve. It’s the early days, but it’s been a huge win for my workflow, personally. It doesn’t take the place of running tests locally while I’m doing TDD cycles, but I’ve made a habit of running the Earthly build locally before I push a PR to minimize the number of failed builds I have on Github Actions.

Personally, I think Earthly is the start of the next-generation of CI tools that will help reduce the gap between local and CI builds. If you have time, I’d highly recommend taking it for a spin and seeing what you think.

We can’t wait to see what folks build with these new features. Previously complex tasks like post processing of files, file progress, and multi-file interactive selections are now a few keystrokes away from your fingertips. Let’s dive in!

Happy coding!

Outside of Phoenix LiveView integration, this release brings other exciting features, including integration with the new Phoenix LiveDashboard. There have been a few deprecations, but this ugprade should be quick and easy for most folks.

Phoenix LiveDashboard

On the heels of the official LiveDashboard release, Phoenix 1.5 projects now ship with LiveDashboard by default, for real-time performance monitoring and debugging tools. It’s at this point I also want to welcome Michael Crumm to the phoenix-core team! He has been heading up the Dashboard work with José Valim, and we can thank them both for the amazing results we have today.

The Dashboard brings you immediate insight into your Phoenix applications with focus on production data. Even if you are just starting with Phoenix, we have tooltips on the widgets so you can learn more about them and if/when you should worry about system limits and the health of your system. With telemetry integration, we also include charting of Phoenix events, along with user-defined metrics.

Check José’s twitter thread to see a breakdown of features and screenshots: https://twitter.com/josevalim/status/1250846714665357315

The dashboard also includes a streaming request logger. This is super convenient for diagnosing an issue in production where you need logs for specific requests but the regular logs drown out your requests in noise. With a button click, you can have all of your own request logs streamed to the dashboard instead of sifting thru a flood of production logs.

We also include a process tab, which is similar to observer, allowing you to sort processes in the system to find large message queues, memory hogs, etc.

Did we mention this Just Works™ for a cluster of distributed nodes? Using the node drop-down selector, you can access all the data/features listed above for any node on the cluster, regardless of what web node you happened to load-balance to when loading the dashboard.

Phoenix LiveView generators

The phx.new project generator now includes a --live flag to include everything you need to get up and running developing with LiveView. Additionally, we have also added a phx.gen.live generator for boostrapping CRUD LiveView context/interfaces similar to phx.gen.html/phx.gen.json. We recommend taking these generators for a test drive to see all the existing improvements to LiveView that recently shipped:

• Revamped LiveViewTest APIs for more powerful, workflow driven testing
• Deep diff tracking for LiveView templates, dramatically reducing server payloads in many cases
• Large performance improvements on client rendering
• Live Navigation with Live Flash

PubSub 2.0

Phoenix.PubSub 2.0 has been released with a more flexible and powerful fastlane mechanism. We took this opportunity to also move Phoenix.PubSub out of the endpoint and explicitly into your supervision tree. This prevents race conditions at startup and decouples your PubSub system from the endpoint. Follow the upgrade guides linked below to get up to speed.

Revamped Guides and more

Thanks to efforts by José Valim, the Phoenix built-in guides have been restructured and revamped, providing a better navigation structure and more content. Be sure to take a look if you’d like to freshen up on your phoenix knowledge.

Other notable improvements include built-in support for MSSQL databases via the tds adapter, and inclusion of the Phoenix.Ecto.CheckRepoStatus plug in new projects to detect and prompt for database creation/migration directly from the comfort of your browser.

As always, we have provided upgrade guides to bring your existing applications up to speed: https://gist.github.com/chrismccord/e53e79ef8b34adf5d8122a47db44d22f

For the complete list of changes, see the CHANGELOG.

Find us on elixir slack/irc if you have questions. Happy coding!

phx_new hex archive

The mix phx.new archive can now be installed via hex, for a simpler, versioned installation experience.

To grab the new archive, simply run:

$ mix archive.uninstall phx_new
$ mix archive.install hex phx_new 1.4.0

The new generators now default to Ecto 3.0, which should be an easy upgrade for existing applications. Ecto 3.0 is packed with new features and improvements, which you can read more about in the Ecto 3.0 sneak peek post.

The new generators also use Milligram in favor of Bootstrap to support classless markup generation. The result is nice looking defaults that allow generated markup to be much more easily customized to your individual CSS requirements.

Note: Existing Phoenix applications will continue to work on Elixir 1.4, but the new phx.new archive requires Elixir 1.5+.

HTTP2

Thanks to the release of Cowboy 2, Phoenix 1.4 supports HTTP2 with a single line change to your mix.exs. Simply add {:plug_cowboy, "~> 2.0"} to your deps and Phoenix will run with the Cowboy 2 adapter.

Local SSL development

Most browsers require connections over SSL for HTTP2 requests, otherwise they fallback to HTTP 1.1 requests. To aid local development over SSL, phoenix includes a new phx.gen.cert task which generates a self-signed certificate for HTTPS testing in development.

See the phx.gen.cert docs for more information.

Faster Development Compilation

Our development compilation speeds have improved thanks to contributions to plug and compile-time changes. You can read more about the details in my DockYard Phoenix post

New Development 404 Page

Our 404 page in development now lists the available routes for the originating router, for example:

UserSocket connection info

A highly requested feature has been access to more underlying transport information when using Phoenix channels. The 1.4 release now provides a connect/3 UserSocket callback, which can provide connection information, such as the peer IP address, host information, and X-Headers of the HTTP request for WebSocket and Long-poll transports.

New Presence JavaScript API

A new, backwards compatible Presence JavaScript API has been introduced to both resolve race conditions as well as simplify the usage. Previously, multiple channel callbacks against "presence_state and "presence_diff" events were required on the client which dispatched to Presence.syncState and Presence.syncDiff functions. Now, the interface has been unified to a single onSync callback and the presence object tracks its own channel callbacks and state. For example:

let presence = new Presence(roomChannel)
presence.onSync(() => {
  console.log("users online:", presence.list((id, {name}) => name))
})

That’s all there is to it!

webpack

The mix phx.new generator now uses webpack for asset generation instead of brunch. The development experience remains the same – javascript goes in assets/js , css goes in assets/css , static assets live in assets/static , so those not interested in JS tooling nuances can continue the same patterns while using webpack. Those in need of optimal js tooling can benefit from webpack’s more sophisticated code bunding, with dead code elimination and more.

What’s Next

With the release of 1.4, we’re ready to focus on other exciting initiatives around the Elixir and Phoenix ecosystem. Most notably, we are excited to integrate telemetry into Phoenix for metric tracking and visualization. Simultaneously, we are also working to rewrite Phoenix.PubSub into smaller building blocks and provide a first-class distributed programming toolkit for the community. You can track this progress over at the Firenest project.

In addition to telemetry and firenest initiatives, we are also working on Phoenix.LiveView, to enable server-rendered real-time experiences without all the complexity of today’s single page application landscape. LiveView can enable rich UX on par with single-page apps in certain usecases and we can’t wait to get the initial release out to the community.

My ElixirConf keynote covers telemetry and LiveView in detail:

Programming Phoenix Book

The Programming Phoenix Book is in beta and available through PragProg, and includes all the latest changes for 1.4. We have titled the book “>= 1.4” and consider it relatively future proof as we continue minor version releases.

Special Thank You’s

I would like to specially thank Loïc Hoguin for his work on Cowboy 2, allowing us to provide a first-class HTTP2 experience. We would also like to thank Bram Verburg, who contributed the local SSL certificate generation, for cross-platform, dependency-free cert generation.

Additionally, I would like to thank José Valim and Plataformatec for their work on the channel layer overhaul which provides an extensible foundation going forward.

As always, we have provided step-by-step instructions for bringing your 1.3.x apps up to speed: https://gist.github.com/chrismccord/bb1f8b136f5a9e4abc0bfc07b832257e

Please report issues to the issue tracker, and find us on #elixir-lang irc, elixir slack, and the Elixir forum if you have any questions. The full list of changes from the changelog can be found here.

Happy hacking!

–Chris

30+ Issues Resolved

The sprint was a success overall as we resolved over 30 issues that achieved several goals, including moving the Phoenix Guides into the core repository and migrating certain of the Guides to blog posts on the Phoenix Site. We also anticipate being able to close a few more issues in the days ahead, resulting in the Phoenix Guides issue queue only having 2-3 remaining open issues.

Thanks to Sprinters

Special thanks to Phoenix core team members who lead the sprint, Gary (@Gazler) & Jason (@jeregrine), and the community members who volunteered their efforts for the day, including: @bryanstearns, @gabiz, @lsiqueira, @mcelaney, @mitchellhenke, and @willykaram. Thanks to all those community members who contributed to the guides prior to the sprint, especially Wendy Smoak(@wsmoak) and Lance Halvorsen (@lancehalvorsen).

Thanks to Sprint Sponsors!

We’d like to thank Jim Freeze and ElixirConf for their support, including sprint facilities and tickets for the sprint leads. Last but not least, we’d like to thank the the organizations that that became sponsors to help fund the sprint and cover the travel costs of Phoenix core team members who joined for the sprint: Apps Team, the Erlang Foundation, Erlang Solutions, Honeybadger.io, plataformatec, RokkinCat, and simplabs.

Next Steps

It was also great to onboard several new contributors to the Phoenix project. Hopefully we can host more contribution sprints at other upcoming regional conferences or local events, and we look forward to ideall welcoming more new contributors there too. We still have more work to do, including improving contribution guidelines and creating suggested guidance for community generated guides – so we’ll see you in the issue queue!

Thanks to everyone we helped us create improved guides to ensure immediate productivity for new developers using Phoenix as a web-interface for their greater Elixir applications!

For those interested in a detailed overview of the changes and design decisions, check out my LonestarElixir keynote: https://www.youtube.com/watch?v=tMO28ar0lW8. Note that the directory structure in the talk is slightly outdated but all ideas still apply.

To use the new phx.new project generator, you can install the archive with the following command:

$ mix archive.install https://github.com/phoenixframework/archives/raw/master/phx_new.ez

1.3.0 uses the phx. prefix on all generators. The old generators are still around though to give the community and learning resources time to catch up. They will be removed on 1.4.0.

As always, we have an upgrade guide with detailed instructions for migrating from 1.2.x projects.

1.3.0 is a backwards compatible release, so upgrading can be as easy as bumping your :phoenix dep in mix.exs to “~> 1.3”. For those wanting to adopt the new conventions, the upgrade guides will take you step-by-step. Before you upgrade, it’s worth watching the keynote or exploring the design decisions outlined below.

Phoenix 1.3 – Design With Intent

The new project and code generators take the lessons learned from the last two years and push folks towards better design decisions as they’re learning. New projects have a lib/my_app directory for business logic and a lib/my_app_web directory that holds all Phoenix related web modules, which are the web interface into your greater Elixir application. Along with new project structure, comes new phx.gen.html and phx.gen.json generators that adopt these goals of isolating your web interface from your domain.

Contexts

When you generate a HTML or JSON resource with phx.gen.html|json, Phoenix will generate code inside a Context. Contexts are dedicated modules that expose and group related functionality. For example, anytime you call Elixir’s standard library, be it Logger.info/1 or Stream.map/2, you are accessing different contexts. Internally, Elixir’s logger is made of multiple modules, such as Logger.Config and Logger.Backends, but we never interact with those modules directly. We call the Logger module the context, exactly because it exposes and groups all of the logging functionality.

For example, to generate a “user” resource we’d run:

mix phx.gen.html Accounts User users email:string:unique

Notice how “Accounts” is a new required first parameter. This is the context module where your code will live that carries out the business logic of user accounts in your application. It could include features like authentication and user registration. Here’s a peek at part of the code that’s generated:

# lib/my_app_web/controllers/user_controller.ex
defmodule MyAppWeb.UserController do
  ...
  alias MyApp.Accounts

  def index(conn, _params) do
    users = Accounts.list_users()
    render(conn, "index.html", users: users)
  end

  def create(conn, %{"user" => user_params}) do
    case Accounts.create_user(user_params) do
      {:ok, user} ->
        conn
        |> put_flash(:info, "user created successfully.")
        |> redirect(to: user_path(conn, :show, user))
      {:error, %Ecto.Changeset{} = changeset} ->
        render(conn, "new.html", changeset: changeset)
    end
  end
  ...
end


# lib/my_app/accounts/accounts.ex
defmodule MyApp.Accounts do
  alias MyApp.Accounts.User

  def list_users do
    Repo.all(User)
  end

  def create_user(attrs \\ %{}) do
    %User{}
    |> User.changeset(attrs)
    |> Repo.insert()
  end
  ...
end

You will also have an Ecto schema generated inside lib/my_app/accounts/user.ex. Notice how our controller calls into an API boundary to create or fetch users in the system. Now we can easily reuse that logic in other controllers, in Phoenix channels, in administrative tasks, etc. Testing also becomes more straight-forward, as we can test the ins and outs of domain without going through the web stack.

Designing with contexts gives you a solid foundation to grow your application from. Using discrete, well-defined APIs that expose the intent of your system allows you to write more maintainable applications with reusable code. Additionally, we can get a glimpse of what the application does and its feature-set just by exploring the application directory structure:

lib
├── my_app
│   ├── accounts
│   │   ├── accounts.ex
│   │   └── user.ex
│   ├── sales
│   │   ├── manager.ex
│   │   ├── sales.ex
│   │   └── ticket.ex
│   └── repo.ex
├── my_app.ex
├── my_app_web
│   ├── channels
│   ├── controllers
│   ├── templates
│   └── views
└── my_app_web.ex

With just a glance at the directory structure, we can see this application has a user Accounts system, as well as sales system. We can also infer that there is a natural API between these systems thru the sales.ex and accounts.ex modules. We gain this insight without seeing a single line of code. Contrast that to the previous web/models, which did not reveal any relationship between files, and mostly reflected your database structure, providing no insight on how they actually related to your domain.

action_fallback

The new action_fallback feature allows you to specify a plug that is called if your controller action fails to return a valid Plug.Conn{} struct. The action fallback plug’s job is then to take the connection before the controller action, as well as the result and convert it to a valid plug response. This is particularly nice for JSON APIs as it removes duplication across controllers. For example, your previous controllers probably looked something like this:

def MyAppWeb.PageController do
  alias MyApp.CMS
  def show(conn, %{"id" => id}) do
    case CMS.get_page(id, conn.assigns.current_user) do
      {:ok, page} -> render(conn, "show.html", page: page)
      {:error, :not_found} ->
        conn
        |> put_status(404)
        |> render(MyAppWeb.ErrorView, :"404")
      {:error, :unauthorized} ->
        conn
        |> put_status(401)
        |> render(MyAppWeb.ErrorView, :"401")
    end
  end
end

This code on its own is fine, but the issue is common data-structures in our domain, such as {:error, :not_found}, and {:error, :unauthorized} must be handled repeatedly across many different controllers. Now there’s a better way with action fallback. With 1.3, we can write:

def MyAppWeb.PageController do
  alias MyApp.CMS

  action_fallback MyAppWeb.FallbackController

  def show(conn, %{"id" => id}) do
    with {:ok, page} <- CMS.get_page(id, conn.assigns.current_user) do
      render(conn, "show.html", page: page)
    end
  end
end


defmodule MyAppWeb.FallbackController do
  def call(conn, {:error, :not_found}) do
    conn
    |> put_status(:not_found)
    |> render(MyAppWeb.ErrorView, :"404")
  end

  def call(conn, {:error, :unauthorized}) do
    conn
    |> put_status(:unauthorized)
    |> render(MyAppWeb.ErrorView, :"401")
  end
end