Combo.CodeReloader (combo v0.8.0)

View Source

A plug and module to handle automatic code reloading.

To avoid race conditions, all code reloads are funneled through a sequential call operation.

Usage

Add the Combo.CodeReloader plug within a code_reloading? block in your endpoint. For example:

if code_reloading? do
  plug Combo.CodeReloader
end

And, Combo.CodeReloader should be configured as a Mix listener in your mix.exs since Elixir v1.18:

def project do
  [
    ...,
    listeners: [Combo.CodeReloader]
  ]
end

This way the reloader can notice whenever your project is compiled concurrently.

Configuration

Combo.CodeReloader is configured via the :code_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.

For example:

config :my_app, MyApp.Web.Endpoint,
  code_reloader: true

config :my_app, MyApp.Web.Endpoint,
  code_reloader: false

config :my_app, MyApp.Web.Endpoint,
  code_reloader: [
    reloadable_apps: [:ui, :backend],
    reloadable_compilers: [:gettext, :elixir]
  ]

The :reloadable_apps option

The :reloadable_apps option defaults to nil, which means reloading the current project if it consists of a single app, or all applications within an umbrella project.

You can set :reloadable_apps to a subset of default applications to reload only some of them, an empty list to effectively disable the code reloader, or include external applications from library dependencies.

The :reloadable_compilers option

The :reloadable_compilers option must be a subset of the :compilers specified in project/0 in your mix.exs.

Notes

Keep in mind code reloading is based on the file-system, therefore it is not possible to run two instances of the same app at the same time with code reloading in development, as they will race each other and only one will effectively recompile the files.

In such cases, tweak your configuration so code reloading is enabled in only one of the apps or set the MIX_BUILD_PATH system environment variable to give them distinct build directories.

Summary

Functions

call(conn, opts)

API used by Plug to invoke the code reloader on every request.

init(opts)

API used by Plug to start the code reloader.

reload(endpoint, opts \\ [])

Reloads code for the current Mix project by invoking the :reloadable_compilers on the list of :reloadable_apps.

reload!(endpoint, opts)

Same as reload/1 but it will raise if Mix is not available.

sync()

Synchronizes with the code server if it is alive.

Functions

call(conn, opts)

API used by Plug to invoke the code reloader on every request.

init(opts)

API used by Plug to start the code reloader.

reload(endpoint, opts \\ [])

@spec reload(
  module(),
  keyword()
) :: :ok | {:error, binary()}

Reloads code for the current Mix project by invoking the :reloadable_compilers on the list of :reloadable_apps.

This function is a no-op and returns :ok if Mix is not available.

Options

  • :reloadable_args - additional CLI args to pass to the compiler tasks. Defaults to ["--no-all-warnings"] so only warnings related to the files being compiled are printed

reload!(endpoint, opts)

@spec reload!(
  module(),
  keyword()
) :: :ok | {:error, binary()}

Same as reload/1 but it will raise if Mix is not available.

sync()

@spec sync() :: :ok

Synchronizes with the code server if it is alive.

It returns :ok. If it is not running, it also returns :ok.