Reloads web pages when files change during development.

How does it work?

Combo.LiveReloader injects JavaScript code into web pages.

The injected JavaScript code will create a WebSocket connection to the server, and wait the messages sent from server.

When a specified file changed, the server will sent a message to the web page , and the web page will be full-reloaded or hot-reloaded in response. By default:

• CSS file changes are hot-reloaded.
• other file changes are full-reloaded.

Usage

Add the Combo.LiveReloader plug within a live_reloading? block in your endpoint. For example:

if live_reloading? do
  socket "/combo/live_reloader/socket", Combo.LiveReloader.Socket
  plug Combo.LiveReloader
end

Configuration

Combo.LiveReloader is configured via the :live_reloader option of your endpoint configuration. The option accepts three types of values:

• true - enable it with default options.
• false - disable it.
• a keyword list - enable it with customized options.

In general, the configuration is added to config/dev.exs. For example:

config :my_app, MyApp.Web.Endpoint,
  live_reloader: [
    patterns: [
      ~r"lib/my_app/web/router.ex",
      ~r"lib/my_app/web/(controllers|layouts|components)/.*.(ex|ceex)$",
      ~r"priv/static/(?!uploads/).*(js|css|png|jpeg|jpg|gif|svg)$"
    ]
  ]

The following options are supported:

• :patterns - a list of patterns to trigger the reloading.

• :path - the path of socket's mount-point. Defaults to /combo/live_reloader/socket.

• :iframe_attrs - the attrs to be given to the injected iframe. Expects a keyword list of atom keys and string values.

• :debounce - an integer in milliseconds to wait before reloading web pages. This prevents rapid successive reloads when multiple files change simultaneously. Default to 100.

• :target_window - the window to be reloaded. Expects :parent or :top . Defaults to :parent.

• :full_reload_on_css_changes - whether to trigger full reload on CSS changes. If true, CSS changes will trigger a full reload like other asset types instead of the default hot reload. Defaults to false.

The :target_window option

• If :parent is set, window.parent will be reloaded.
• If :top is set, window.top will be reloaded.

Skipping remote CSS reload

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. For example:

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

Backends

This module uses FileSystem to watch the file system changes. It supports the following backends:

• :fs_inotify - available on Linux and BSD. It requires installing an extra package, check out the wiki of inotify-tools for more details.
• :fs_mac - available on macOS.
• :fs_windows - available on Windows.
• :fs_poll - available on all operating systems.

In general, the backend is set automatically. But if you want to set it manually, do it like:

config :combo, :live_reloader, backend: :fs_poll

By default the entire application directory is watched. However, with some environments and backends, this may be inefficient, resulting in slow response times to file modifications. To account for this, it's 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 :combo, :live_reloader,
  dirs: [
    "priv/static",
    "priv/gettext",
    "lib/my_app/web/layouts",
    "lib/my_app/web/controllers",
    "../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
  ]