Phoenix LiveView - 1.2.0 released

LiveView 1.2.0 is out now!

Colocated CSS

The biggest new feature is support for Colocated CSS, which is built on the work we did in 1.1 for Colocated Hooks and Colocated JS.

def table(assigns) do
  ~H"""
  <style :type={MyAppWeb.ColocatedCSS}>
    thead color: {
      ...;
    }
    tbody, tr:hover {
      ...
    }
  </style>
  <table>...</table>
  """
end

You can optionally scope colocated CSS to only the component it is defined in. We don’t ship a built in scoping mechanism for now, but the docs include an example using CSS @scope.

To implement this, we did a big refactor of how we compile HEEx templates, which we explain in a separate blog post.

tl;dr: To make colocated CSS work, we had to change how we compile HEEx templates by splitting compilation into a separate tokenization and parsing step, allowing us to handle macro components (colocated CSS and JS) without making the rest of the compilation more complex. It also allowed us to reuse code we previously had to duplicate between template compilation and formatting.

Formatters for <script> and <style> tags

The Phoenix.LiveView.HTMLFormatter.TagFormatter behaviour allows you to format <script> and <style> tags with third party tooling when running mix format, especially useful if your project uses colocated assets like Phoenix.LiveView.ColocatedHook or the new ColocatedCSS.

The documentation contains an example using prettier, which we also use in the LiveView repository itself.

Encoding JS commands to JSON

Phoenix.LiveView.JS structs can now be encoded to JSON for usage in push_event. So now you can do

push_event(socket, "highlight", %{toggle: JS.toggle_class(...)})

// some hook
this.handleEvent("highlight", ({ toggle }) => { this.js().execJS(this.el, toggle); });

while in the past you’d have to render the command in an element attribute and then refer back to it in your hook.

LiveView implements JSON.Encoder and Jason.Encoder automatically. If you use a different library, you can invoke JS.to_encodable/1 manually.

Thank you to @rhcarvalho for contributing this in response to Make `JS.t()` a public data structure, or json serializable.

Opting out of debug annotations

You can now opt-out of the HEEx debug annotations (HTML comments and attributes) per module with

@debug_heex_annotations false
@debug_attributes false

This was done in response to Disable HEEx debug annotations conditionnaly.

Granular configuration for test warnings

In previous releases, we started to add some checks when running LiveView tests, for example to warn you if there’s a duplicated ID on the page (that will cause problems in the browser). In LiveView 1.2, we added a new check to warn about forms with a missing ID, which prevents [form recovery] from working. Because there are cases where an ID is deliberately omitted and form recovery is not needed, all of those checks can now be configured on their own:

config :phoenix_live_view, :test_warnings,
 duplicate_id: :warn, # one of :warn, :raise, :ignore
 ...

See the documentation for more details.

Documentation for the JS client

While many people like that they’re able to avoid touching JavaScript when using LiveView, there are cases where creating hooks and interacting with the LiveSocket API are needed. We now have dedicated documentation on the JS client that shows the public API, based on typedoc.

Links

See the official announcement for more details:

Also have a look at the HEEx compilation deep dive if you’re interested:

Finally, have a look at the changelog for more details on bugs and other small enhancements.

Happy coding!