Phoenix 🦩

Naming
Dependencies
Release
Environment Configuration
Project Structure
Database
Database Migration

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.

# Bad
mix phx.new project_name
mix phx.new project_name --live
mix phx.new project_name --no-html --no-webpack

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

Use the team template for all Phoenix projects.

Use snake_case for both database tables and columns.

Use plural for database tables and singular for column names.

+---------------------------+
| campaign_locations        |
+-------------+-------------+
| id          | ID          |
| name        | STRING      |
| location_id | FOREIGN KEY |
| updated_at  | DATETIME    |
+-------------+-------------+

For many-to-many associations, use plural for the joined tables

create table(:posts) do
  add :title, :string
  add :body, :text
  timestamps()
end

create table(:tags) do
  add :name, :string
  timestamps()
end

# Bad
create table(:post_tags, primary_key: false) do
  add :post_id, references(:posts)
  add :tag_id, references(:tags)
end

# Good
create table(:posts_tags, primary_key: false) do
  add :post_id, references(:posts)
  add :tag_id, references(:tags)
end

Use predicate-like name for boolean database columns.

# Bad
alter table("users") do
  add :enabled, :boolean, null: false
end

# Good
alter table("users") do
  add :is_enabled, :boolean, null: false
end

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

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

# Good
Multi.new()
|> Multi.update(:update_comment, fn _ -> ... end)
|> Multi.run(:publish_post, fn _, _ -> ... 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.

Project Structure

Follow the default structure from the Phoenix guide.

├── _build
├── assets
├── config
├── deps
├── lib
│   └── project_name
│   └── project_name_web
│   └── 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, we could put the User in the Account context

├── project_name
│   ├── 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
│   ├── account
│   │   ├── users.ex # Contains all Accounts User Repo actions (eg: list_all, get_by_username)
│   │   ├── queries
│   │   │   └── user_query.ex # Contains all Accounts User Queries
│   │   └── schemas
│   │       └── user.ex # Contains Accounts User Schema and all Accounts User Changesets

Web

The /project_name_web directory hosts all web-related parts.
When adding “non-conventional” directories in /project_name_web, use the plural for the directory name
```
├── project_name_web
│   └── params
│   └── plugs
```

LiveView

Adding _live suffix to the folder and the live module

# less preferred
├── live
│   └── verification
│       └── show.ex
    
# preferred
├── live
│   └── verification_live
│       └── show_live.ex

Adding_component suffix to LiveView Component for both LiveView Module and LiveView template

Prefer to keep all LiveView components inside the components folder.

# less preferred
├── live
│   └── verification_live
│       └── item.ex
│       └── show_live.ex
├── templates
│   └── verification
│       └── item.html.leex
│       └── show.html.html.leex
└── views
    └── verification_view.ex
    
# preferred    
├── live
│   └── verification_live
│       └── components
│           └── item_component.ex
│       └── show_live.ex
├── templates
│   └── verification
│       └── components
│           └── item_component.html.leex
│       └── show.html.html.leex
└── views
    └── verification_view.ex

Keep all LiveView templates (*.html.leex) under the /templates folder instead of the /live folder, use Phoenix.View.render/3 to render a specific LiveView template.

# project-name-web/lib/project_name_web/live/verification_live/show_live.ex
@impl true
def render(assigns) do
  Phoenix.View.render(VerificationView, "show.html", assigns)
end
    
# project-name-web/lib/project_name_web/live/verification_live/components/item_component.ex
@impl true
def render(assigns) do
  Phoenix.View.render(VerificationView, "components/item_component.html", assigns)
end

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

Prefer expressions syntax for Ecto queries.

# Least preferred
from(p in Payment, where: p.status == "pending")

# Preferred
Payment
|> where([p], p.status == "pending")

Database Migration

Name the migration files more elaborately. For table migrations, suppose you add/drop any column to/from a table then, keep both column_name and table_name in migration name. The name of the migration name (e.g. DropSurnameFromUsers). For migrations with multiple actions, group the column names and table names in the class name. So the general template is [ChangeMade]+To/From+[TableNamePlural]

# Bad
defmodule ProjectName.Repo.Migrations.DropSurnameColumn
  use Ecto.Migration
    
  def change
    alter table(:users) do
      remove :surname
    end
  end
end

# Good
defmodule ProjectName.Repo.Migrations.DropSurnameFromUsers
  use Ecto.Migration
    
  def change
    alter table(:users) do
      remove :surname
    end
  end
end

defmodule ProjectName.Repo.Migrations.DropSurnameNicknameFromUsers
  use Ecto.Migration
    
  def change
    alter table(:users) do
      remove :surname
      remove :nickname
    end
  end
end

For data migration, use a descriptive name.

# Bad
defmodule ProjectName.Repo.Migrations.UpdateWebsite
  use Ecto.Migration
    
  def change
    # your changes to DB here
  end
end

# Good
defmodule ProjectName.Repo.Migrations.UpdateWebsiteColumnOfUsers
  use Ecto.Migration
    
  def change
    # your changes to DB here
  end
end

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

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