PlugLiveReload

Adds live-reload functionality to Plug for development.

Installation

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

defp deps do
 [
   {:plug_live_reload, "~> 0.2.0", only: :dev}
 ]
end

Once that is done, you will want to add the plug to your Plug.Router.

defmodule MyApp.Router do
  use Plug.Router

  if Mix.env() == :dev do
    plug PlugLiveReload
  end
  
  plug :match
  plug :dispatch

  get "/" do
    conn
    |> put_resp_content_type("text/html")
    |> send_resp(200, "<html><body><h1>Plug</h1></body></html>")
  end
end

You will additionally need to make sure the PlugLiveReload.Socket handler is added to your Plug.Cowboy child spec in your application.

def start(_type, _args) do
  children = [
    {Plug.Cowboy, scheme: :http, plug: MyApp.Router, options: [
      port: 4000,
      dispatch: dispatch()
    ]}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

if Mix.env() == :dev do
  def dispatch(),
    do: [
      {:_,
       [
        {"/plug_live_reload/socket", PlugLiveReload.Socket, []},
        {:_, Plug.Cowboy.Handler, {MyApp.Router, []}}
       ]}
    ]
else
  def dispatch(), do: nil
end

Lastly, you will need to configure which file paths to watch.

# config/dev.exs

config :plug_live_reload,
  patterns: [
    ~r"priv/static/.*(js|css|png|jpeg|jpg|gif|svg)$",
  ]

You can find additional documentation for configuring the PlugLiveReload plug and the PlugLiveReload.Socket in their respective documentation pages.

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 :plug_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, and additional options for the backend:

config :plug_live_reload,
  dirs: [
    "priv/static",
    "priv/gettext",
    "lib/example_web/live",
    "lib/example_web/views",
    "lib/example_web/templates",
  ],
  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>

Credits

Most of this code was adapted from phoenix_live_reload. The main difference is that this package is plug-specific and takes no Phoenix dependencies.