phoenixframework/phoenix_live_reload

A project for live-reload functionality for Phoenix during development.

Usage

You can use phoenix_live_reload in your projects by adding it to your mix.exs dependencies:

def deps do
  [{:phoenix_live_reload, "~> 1.5"}]
end

You can configure the reloading interval in ms in your config/dev.exs:

# Watch static and templates for browser reloading.
config :my_app, MyAppWeb.Endpoint,
  live_reload: [
    interval: 1000,
    patterns: [
      ...

The default interval is 100ms.

Streaming serving logs to the web console

Note: This feature is only available for Elixir v1.15+

Streaming server logs that you see in the terminal when running mix phx.server can be useful to have on the client during development, especially when debugging with SPA fetch callbacks, GraphQL queries, or LiveView actions in the browsers web console. You can enable log streaming to colocate client and server logs in the web console with the web_console_logger configuration in your config/dev.exs:

config :my_app, MyAppWeb.Endpoint,
  live_reload: [
    interval: 1000,
    patterns: [...],
    web_console_logger: true
  ]

Next, you'll need to listen for the "phx:live_reload:attached" event and enable client logging by calling the reloader's enableServerLogs() function, for example:

window.addEventListener("phx:live_reload:attached", ({detail: reloader}) => {
  // enable server log streaming to client.
  // disable with reloader.disableServerLogs()
  reloader.enableServerLogs()
})

Each log line is also emitted as a "phx:live_reload:log" event on the window, which can be used by third party devtools.

window.addEventListener("phx:live_reload:log", ({detail: { level, message, metadata }}) => {
  // level is one of "debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"
  // message is the log message string
  // metadata is a map of log metadata, including by default: pid, line, file
})

You can configure additional metadata to be included in the log event by setting the :web_console_logger_forward_metadata option in your config/dev.exs:

config :my_app, MyAppWeb.Endpoint,
  live_reload: [
    web_console_logger_forward_metadata: [:time]
  ]

Values have to be JSON-serializable.

Jumping to HEEx function definitions

Many times it's useful to inspect the HTML DOM tree to find where markup is being rendered from within your application. HEEx supports annotating rendered HTML with HTML comments that give you the file/line of a HEEx function component and caller. :phoenix_live_reload will look for the PLUG_EDITOR environment export (used by the plug debugger page to link to source code) to launch a configured URL of your choice to open your code editor to the file-line of the HTML annotation. For example, the following export on your system would open vscode at the correct file/line:

export PLUG_EDITOR="vscode://file/__FILE__:__LINE__"

The vscode:// protocol URL will open vscode with placeholders of __FILE__:__LINE__ substituted at runtime. Check your editor's documentation on protocol URL support. To open your configured editor URL when an element is clicked while a shortcut key is held, enable editor shortcuts within your "phx:live_reload:attached" callback and configure the keys for the caller and function component definition. For example:

window.addEventListener("phx:live_reload:attached", ({detail: reloader}) => {
  // Enable server log streaming to client. Disable with reloader.disableServerLogs()
  reloader.enableServerLogs()

  // Open configured PLUG_EDITOR at the clicked element's HEEx caller or
  // function component definition. Disable with reloader.disableEditorShortcuts()
  reloader.enableEditorShortcuts({caller: "c", definition: "d"})
  window.liveReloader = reloader
})

Both the caller and definition keys are required. Calling enableEditorShortcuts again replaces the existing shortcuts. The lower-level openEditorAtCaller and openEditorAtDef functions remain available when you need to provide your own event handling, for example:

// Open configured PLUG_EDITOR at file:line of the clicked element's HEEx component
//
//   * click with "c" key pressed to open at caller location
//   * click with "d" key pressed to open at function component definition location
let keyDown
window.addEventListener("keydown", e => keyDown = e.key)
window.addEventListener("keyup", e => keyDown = null)
window.addEventListener("click", e => {
  if(keyDown === "c"){
    e.preventDefault()
    e.stopImmediatePropagation()
    reloader.openEditorAtCaller(e.target)
  } else if(keyDown === "d"){
    e.preventDefault()
    e.stopImmediatePropagation()
    reloader.openEditorAtDef(e.target)
  }
}, true)

Backends

This project uses FileSystem as a dependency to watch your filesystem whenever there is a change and it supports the following operating systems:

• Linux via inotify (installation required)
• Windows via inotify-win (no installation required)
• Mac OS X via fsevents (no installation required)
• FreeBSD/OpenBSD/~BSD via inotify (installation required)

There is also a :fs_poll backend that polls the filesystem and is available on all Operating Systems in case you don't want to install any dependency. You can configure the :backend in your config/config.exs:

config :phoenix_live_reload,
  backend: :fs_poll

By default the entire application directory is watched by the backend. However, with some environments and backends, this may be inefficient, resulting in slow response times to file modifications. To account for this, it's also possible to explicitly declare a list of directories for the backend to watch (they must be relative to the project root, otherwise they are just ignored), and additional options for the backend:

config :phoenix_live_reload,
  dirs: [
    "priv/static",
    "priv/gettext",
    "lib/example_web/live",
    "lib/example_web/views",
    "lib/example_web/templates",
    "../another_project/priv/static", # Contents of this directory is not watched
    "/another_project/priv/static", # Contents of this directory is not watched
  ],
  backend: :fs_poll,
  backend_opts: [
    interval: 500
  ]

Skipping remote CSS reload

All stylesheets are reloaded without a page refresh anytime a style is detected as having changed. In certain cases such as serving stylesheets from a remote host, you may wish to prevent unnecessary reload of these stylesheets during development. For this, you can include a data-no-reload attribute on the link tag, ie:

<link rel="stylesheet" href="http://example.com/style.css" data-no-reload>

Differences between Phoenix.CodeReloader

Phoenix.CodeReloader recompiles code in the lib directory. This means that if you change anything in the lib directory (such as a context) then the Elixir code will be reloaded and used on your next request.

In contrast, this project adds a plug which injects some JavaScript into your page with a WebSocket connection to the server. When you make a change to anything in your config for live_reload (JavaScript, stylesheets, templates and views by default) then the page will be reloaded in response to a message sent via the WebSocket. If the change was to an Elixir file then it will be recompiled and served when the page is reloaded. If it is JavaScript or CSS, then only assets are reloaded, without triggering a full page load.

License

Same license as Phoenix.