PhoenixHisto

A plug for handling client side routing in Phoenix, a.k.a. History Api fallback.

Rationale

Single page applications use History Api to enable client side routing. This plug allows for handling client side routes on the server by rewriting requests to index.html.

Requests exempt from rewrite

The fallback algorithm is limited only to certain requests. In particular it will not rewrite if:

• request method is not GET or HEAD.
• it is a file request, e.g. "/path/file.ext"; note that if PhoenixHisto is plugged after Plug.Static and we get a file request than most likely the file does not exist and 404 response will be returned
• the client does not accept text/html response MIME type
• the requested path starts with one of the paths in :blacklist

Installation

The package can be installed by adding phoenix_histo to your list of dependencies in mix.exs:

def deps do
  [
    {:phoenix_histo, "~> 1.0.0"}
  ]
end

Usage

Add plug invocation in your Endpoint pipeline just after Plug.Static:

defmodule MyAppWeb.Endpoint do
  use Phoenix.Endpoint, otp_app: :my_app
  ...
  @static_opts [at: "/", from: :my_app, gzip: false]
  plug Plug.Static,
    (@static_opts ++
    [only: ~w(css fonts img js favicon.ico robots.txt manifest.json)])
  plug PhoenixHisto,
    static_opts: @static_opts,
    blacklist: ["/api"]
  ...
end

Options

• :index - path to index.html fallback relative to the dir passed in :static_opts (defaults to "index.html").
• :blacklist - list of path prefixes exempt from fallback algorithm (defaults to []).
• :static_opts - options to forward to Plug.Static (required), refer to Plug.Static docs. Note that :only and :only_matching are not respected.

Documentation

Docs can be found at https://hexdocs.pm/phoenix_histo.

License

PhoenixHisto source code is released under MIT License. Check LICENSE file for more information.