nimblehq.co

Phoenix 🦩

Hero image for Phoenix 🦩

All Elixir conventions apply to Phoenix projects. Additionally, when working with the Phoenix framework, a superset of conventions must be followed.

Naming

  • Suffix each project root name with -web or -api depending on the project type.

    mix phx.new project_name
mix phx.new project_name --no-live
mix phx.new project_name --no-html --no-assets

    mix phx.new project-name-web --module ProjectName --app project_name
mix phx.new project-name-web --module ProjectName --app project_name --no-live
mix phx.new project-name-api --module ProjectName --app project_name --no-html --no-assets

    Use the team template for all Phoenix projects.

  • Name Ecto.Multi operations with meaningful naming that provides context to the function performed.

    Multi.new()
|> Multi.update(:comment, fn _ -> ... end)
|> Multi.run(:post, fn _, _ -> ... end)

    Multi.new()
|> Multi.update(:update_comment, fn _ -> ... end)
|> Multi.run(:publish_post, fn _, _ -> ... end)

  • Prefer naming the normal HTML template files in snake_case e.g. product_detail.html.eex and use _ prefix for the partial HTML template filenames e.g. _movie.html.eex.

      <%= for movie <- @movies do %>
    <%= render "_movie.html", movie: movie, conn: @conn %>
  <% end %>

Dependencies

Dependencies in mix.exs must be sorted in alphabetical order.

defp deps do
  [
    {:argon2_elixir, "~> 2.0"},
    {:credo, "~> 1.5.5", [only: [:dev, :test], runtime: false]},
    {:dialyxir, "~> 1.1.0", [only: [:dev], runtime: false]},
    {:ecto_sql, "~> 3.4"},
    {:ex_machina, "~> 2.7.0", [only: [:dev, :test]]},
    {:excoveralls, "~> 0.14.0", [only: :test]},
    {:faker_elixir_octopus, "~> 1.0.0", only: [:dev, :test]}
    {:gettext, "~> 0.11"},
    {:guardian, "~> 2.0"},
    {:jason, "~> 1.0"},
    {:mimic, "~> 1.4.0", [only: :test]},
    {:oban, "~> 2.5.0"},
    {:phoenix, "~> 1.5.8"},
    {:phoenix_ecto, "~> 4.1"},
    {:phoenix_html, "~> 2.11"},
    {:phoenix_live_dashboard, "~> 0.4"},
    {:phoenix_live_reload, "~> 1.2", only: :dev},
    {:plug_cowboy, "~> 2.0"},
    {:postgrex, ">= 0.0.0"},
    {:sobelow, "~> 0.11.1", [only: [:dev, :test], runtime: false]},
    {:telemetry_metrics, "~> 0.4"},
    {:telemetry_poller, "~> 0.4"},
    {:wallaby, "~> 0.28.0", [only: :test, runtime: false]},
  ]
end

After initializing a new project or when adding a new dependency, the list of dependencies must be arranged manually.

Release

Prefer releasing the application with mix release or distillery instead of mix mode.

Environment Configuration

  • Place all environment variables in config/prod.secret.exs (mix mode) or config/runtime.exs (mix release mode with Elixir ~> 1.11).

  • Use System.fetch_env! to access environment variables in config/prod.secret.exs or config/runtime.exs.

    config :new_relic_agent,
  app_name: System.fetch_env!("NEW_RELIC_APP"),
  license_key: System.fetch_env!("NEW_RELIC_LICENSE")

    Since this file is loaded on application boot, it will fail if an environment variable is missing i.e. fast-fail strategy.

Routes

  • Prefer to create a separate scope per pipe_through statement. It will be easier to group and manage routes.

    scope "/v1", AwesomeApp, as: :api_v1 do
  pipe_through :api

  get "/health_check", V1.HealthCheckController, :index

  pipe_through [:api, :require_authenticated_user]

  get "/me", V1.UserController, :show
end

    scope "/v1", AwesomeApp, as: :api_v1 do
  scope "/" do
    pipe_through :api

    get "/health_check", V1.HealthCheckController, :index
  end

  scope "/" do
    pipe_through [:api, :require_authenticated_user]

    get "/me", V1.UserController, :show
  end
end

Project Structure

Follow the default structure from the Phoenix guide.

├── _build
├── assets
├── config
├── deps
├── lib
│   └── project_name
│   └── project_name_web
│   └── project_name_worker
│   └── project_name.ex
│   └── project_name_web.ex
├── priv
└── test

Business Domain

  • The /project_name directory hosts all business domains.

  • Use Context to decouple and isolate the systems into manageable and independent parts.

  • Prefer to use contexts every time, even if that context has a single model.

  • Prefer to keep the context name singular.

    For example, the User could be put in the Account context

    ├── project_name
│   ├── account
│   │   ├── users.ex # Contains all Account User Repo actions (eg: list_all, get_by_username)
│   │   └── helpers
│   │       └── account_helper.ex # Contains Account helpers.
│   │   ├── queries
│   │   │   └── user_query.ex # Contains all Accounts User Queries
│   │   └── schemas
│   │       └── user.ex # Contains Account User Schema and all Accounts User Changesets
│   ├── exception # Contains all custom exceptions (eg: PlayerNotFoundException, InvalidTokenException)
│   │       ├── invalid_token_exception.ex
│   │       └── player_not_found_exception.ex
│   ├── game
│   │   ├── games.ex # Contains all Game Context actions (eg: save_game_state, load_game_state)
│   │   ├── heroes.ex # Contains all Game Hero Repo actions (eg: list_all, get_by_name)
│   │   ├── items.ex # Contains all Game Item Repo actions (eg: list_all, get_by_slug)
│   │   ├── queries
│   │   │   ├── hero_query.ex # Contains all Game Hero Queries
│   │   │   └── item_query.ex # Contains all Game Item Queries
│   │   └── schemas
│   │       ├── hero.ex # Contains Game Hero Schema and all Game Hero Changesets
│   │       └── item.ex # Contains Game Item Schema and all Game Item Changesets

Web

  • The /project_name_web directory hosts all web-related parts.

  • Group all helpers for the web application in the /helpers directory since some helpers can be shared among controllers, views, or templates.

    ├── awesome_web
│   ├── helpers
│   │  ├── error_helper.ex
│   │  ├── input_helper.ex
│   │  └── layout_helper.ex

  • When adding “non-conventional” directories in /project_name_web, use the plural for the directory name

    ├── project_name_web
│   └── params
│   └── plugs

LiveView

  • Add the _live suffix to the LiveView modules.

    # less preferred
├── live
│   └── verification  # Context
│       └── show.ex   # LiveView module

    # preferred
├── live
│   └── verification      # Context
│       └── show_live.ex  # LiveView module

  • Add the _component suffix to LiveComponent modules.

  • Prefer to place all LiveComponent inside the components directory.

      ├── live
  |   └── articles  # Context
  |       ├── components
  │       │   ├── table_component.ex        # LiveComponent module
  │       │   └── table_component.html.heex # LiveComponent template

  • Place all templates for LiveView/LiveComponent (*.html.heex) under the /live directory alongside their live module, and use the same name as the live module.

    ├── live
│   └── verification  # Context
|       ├── components
│       │   ├── item_component.ex         # LiveComponent module
│       │   └── item_component.html.heex  # LiveComponent template
│       ├── show_live.ex      # LiveView module
│       └── show.html.heex    # LiveView template

Non-conventional Directories

  • When adding “non-conventional” directories in /lib, use the project_name as a prefix and singular for the directory name

    ├── lib
│   └── project_name_mail
│   └── project_name_worker

Database

All practices on the Web - Database page apply to Phoenix projects. The following section brings practices and recommendations specific to Phoenix projects.

  • Prefer Pipe-based syntax over Keyword-based for Ecto queries.

    from(p in Payment, where: p.status == "pending", select: p.status)

    Payment
|> where([p], p.status == "pending")
|> select([:status])

Database Migration

  • Prefer to use multiple migration directories to separate long-running migrate tasks.

    ├── priv
│   └── repo
│       ├── migrations # run automatically
│       ├── manual_migrations # run manually

  • Avoid calling application modules or functions within migration files.

    defmodule AwesomeApp.Repo.Migrations.AddLocaleToUsers do
  use Ecto.Migration

  # Bad
  alias AwesomeApp.Users

  def change do
    alter table(:users) do
      add(:locale, :string)
    end

    # Bad
    Users.update_users_locale()
  end
end

  • For the data migration, prefer to use SQL commands or release tasks depending on the data complexity.

    Using SQL commands is the preferred option if the migrating data are straightforward, such as fixed value or current datetime.

    defmodule AwesomeApp.Repo.Migrations.AddLocaleToUsers do
  use Ecto.Migration

  def change do
    alter table(:users) do
      add(:locale, :string)
    end

    execute("UPDATE Users SET locale='EN'", "")
  end
end

    If the migrating data are complex or require business logic, prefer creating release tasks and running them once the changes are deployed.

    defmodule AwesomeApp.Repo.Migrations.AddLocaleToUsers do
  use Ecto.Migration

  def change do
    alter table(:users) do
      add(:locale, :string)
    end
  end
end

defmodule AwesomeApp.ReleaseTasks do
  def update_users_locale() do
    # Iterating through users and determining their locale 
    # depends on the business logic.
  end
end

  • Always define down operation SQL commands for the execute/2 to make the migration reversible.

    defmodule AwesomeApp.Repo.Migrations.MyMigration do
  use Ecto.Migration

  def change do
    execute execute_up(), execute_down()
  end

  defp execute_up, do: "CREATE EXTENSION IF NOT EXISTS citext"
  defp execute_down, do: "DROP EXTENSION IF EXISTS citext"
end

LiveView

  • For live modules (LiveView/LiveComponent), prefer to separate the template to its HEEx template file by omitting the render/1 function inside the live module and placing the template file alongside the module.

    ├─ live/
│  ├─ landings/
|  |  ├─ components/
│  │  │  ├─ greeting_component.ex          # LiveComponent module
│  │  │  ├─ greeting_component.html.heex   # LiveComponent's template
|  |  ├─ show_live.ex     # LiveView module
|  |  ├─ show.html.heex   # LiveView's template

Event Handlers

  • Prefer using a string for an event name in the handle_event/3 callback as it works on both HTML tag and HEEx template.

    <button type="button" phx-click="increase_temperature"></button>

    <%= content_tag :button, type: "button", phx_click: "increase_temperature" %>

    def handle_event("increase_temperature", _value, socket) do
  new_temperature = socket.assigns.temperature + 1

  {:noreply, assign(socket, :temperature, new_temperature)}
end

  • Prefer using an atom when sending and handling a message in the handle_info/2 callback as it is an internal message and rarely changes.

      # Message without payload
  def handle_info(:increase_temperature, socket) do
    new_temperature = socket.assigns.temperature + 1

    {:noreply, assign(socket, :temperature, new_temperature)}
  end

  # Message with payload
  def handle_info({:increase_temperature, value}, socket) do
    new_temperature = socket.assigns.temperature + value

  {:noreply, assign(socket, :temperature, new_temperature)}
end

Gettext

  • Prefer to use a specific Domain for translation.

    gettext("Failed to get user")
ngettext("1 product", "%{count} products", length(@products))

    dgettext("errors", "Failed to get user")
dngettext("product", "1 product", "%{count} products", length(@products))

Plug

  • Prefer module plugs over function plugs.

  • Place all module plugs in the directory project_name_web/plugs.

    defmodule ProjectNameWeb.SampleController do
  use ProjectNameWeb, :controller

  plug :ensure_item_exists when action in [:new]

  def new(conn, _) do
    # ...
  end

  defp ensure_item_exists(conn, _options) do
    # ...
  end
end

    defmodule ProjectNameWeb.EnsureItemExistsPlug do
  import Plug.Conn

  @impl true
  def init(opts), do: opts

  @impl true
  def call(conn, _opts) do
    # ...
  end
end

defmodule ProjectNameWeb.SampleController do
  use ProjectNameWeb, :controller

  plug EnsureItemExistsPlug when action in [:new]

  def new(conn, _) do
    # ...
  end
end

Worker

Distributed Cluster

  • Prefer to use libcluster to form the cluster.
  • Prefer to use horde to distribute Supervisor and Registry across nodes.