Usage

Requirements

• Elixir >=1.11
• Phoenix >= 1.6.0
• Phoenix LiveView >= 0.16 (optional)

Adding Routex to your project

You can install this library by adding it to your list of dependencies in mix.exs. (use mix hex.info routex to find the latest version):

def deps do
  [
     ...other deps
+    {:routex, "~> 1.0"}
  ]
end

Next run:

mix deps.get

Quick config using Igniter

Routex includes an Igniter install task that automates the setup process, eliminating the need for manual file editing.

You can install Igniter adding it to your list of dependencies in mix.exs. (use mix hex.info igniter to find the latest version):

def deps do
  [
     ...other deps
     {:routex, "~> 1.0"},
+    {:igniter, "~> 0.6"}
  ]
end

Even though Igniter handles the installation automatically, it's recommended to review the rest of this page to understand how Routex works and how you can customize it to fit your specific needs.

mix deps.get
mix routex.install

Manual config

Modify the entrypoint of your web interface definition.

# file: lib/example_web.ex

# in router
+  use Routex.Router  # always before Phoenix Router
   use Phoenix.Router, helpers: false

# in controller
   unquote(verified_routes())
+  unquote(routex_helpers())

q
# in live_view
      unquote(html_helpers())
+     on_mount(unquote(__MODULE__).Router.RoutexHelpers)

# in view_helpers or html_helpers
   unquote(verified_routes())
+  unquote(routex_helpers())

# insert new private function
+  defp routex_helpers do
+    quote do
+      import Phoenix.VerifiedRoutes,
+        except: [sigil_p: 2, url: 1, url: 2, url: 3, path: 2, path: 3]
+
+      import unquote(__MODULE__).Router.RoutexHelpers, only: :macros
+      alias unquote(__MODULE__).Router.RoutexHelpers, as: Routes
+    end
+  end

Configuration

To use Routex, a module that calls use Routex.Backend (referred to below as a "backend") has to be defined. It includes a list with extensions and configuration of extensions.

Too speed up setup all extensions are included in the configuration below.

# file /lib/example_web/routex_backend.ex

defmodule ExampleWeb.RoutexBackend do
 use Routex.Backend,
   extensions: [
     # required
     Routex.Extension.AttrGetters,

     # adviced
     Routex.Extension.LiveViewHooks,
     Routex.Extension.Plugs,
     Routex.Extension.VerifiedRoutes,
     Routex.Extension.Alternatives,
     Routex.Extension.AlternativeGetters,
     Routex.Extension.Assigns,
     Routex.Extension.Localize.Phoenix.Routes,
     Routex.Extension.Localize.Phoenix.Runtime,
     Routex.Extension.RuntimeDispatcher

     # optional
     # Routex.Extension.Translations,  # when you want translated routes
     # Routex.Extension.Interpolation, # when path prefixes don't cut it
     # Routex.Extension.RouteHelpers,  # when verified routes can't be used
     # Routex.Extension.Cldr,          # when combined with the Cldr ecosystem
   ],
   assigns: %{namespace: :rtx, attrs: [:locale, :language, :region]},
   verified_sigil_routex: "~p",
   verified_url_routex: :url,
   verified_path_routex: :path
end

Preprocess routes with Routex

Routex will preprocess any route found inside a preprocess_using block, either directly or nested in other blocks such as scope.

preprocess_using receives the backend module name as the first argument. This allows the use of distinct backends per preprocess_using block (e.g. to use different extensions for admin routes)

# file: router.ex
  pipeline :browser do
      [..]
      plug :put_secure_browser_headers
      plug :fetch_current_user
+     plug :routex
  end

+ preprocess_using ExampleWeb.RoutexBackend do
    scope "/", ExampleWeb do
      pipe_through [:browser, :redirect_if_user_is_authenticated]
      # [...routes...]
    end

    scope "/", ExampleWeb do
      pipe_through [:browser, :require_authenticated_user]
      # [...routes...]
    end
+ end

Configuring individual extensions

In the configuration above, a number of extensions are enabled with sensible defaults to help you get started quickly. Don’t worry though; they’re all highly customizable, so you can adjust them to fit your needs.

Each extension focuses on a single feature and comes with its own documentation that explains how to set it up and use it. If you’d like a quick overview along with links to the docs for each extension, check out the Extensions Overview.

Help?

When you run into issues, please have a look at the Troubleshooting guide and Elixir Forum