Ash Setup Guide

Ash provides a powerful tool called Igniter that makes setting up new projects much easier. This guide will show you the recommended approach using Igniter, as well as explaining the manual steps for those who prefer that approach.

The Igniter Approach (Recommended)

Igniter is a powerful code generator that can scaffold Ash applications and add packages to existing applications. It’s the recommended way to set up Ash projects.

First, install the igniter_new archive:

$ mix archive.install hex igniter_new

Then create a new application with Ash pre-installed:

$ mix igniter.new app --install ash
$ cd app

If you’d like to create a Phoenix application with Ash, you can use:

$ mix igniter.new app --with phx.new --install ash,ash_postgres
$ cd app

This will create a new application with all the necessary dependencies, configuration files, and folder structure for working with Ash.

The Manual Approach (Alternative)

If you prefer to set up your Ash application manually, here are the steps:

Let’s start with a fresh Mix project:

$ mix new --sup app
$ cd app

We add Ash to our dependencies in mix.exs (find the latest version number at https://hex.pm/packages/ash):

mix.exs
[...]
defp deps do
  [
    {:ash, "~> 3.0"}
  ]
end
[...]

Run mix deps.get to install it:

$ mix deps.get

To make sure that we get the right formatting for our code, we change the file .formatter.exs to include the Ash formatter:

.formatter.exs
[
  import_deps: [:ash],
  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
]
The Elixir formatter is a great tool to keep your code consistent. It is highly recommended to use run the command mix format before committing your code into a repository.

Adding Ash to Existing Projects

If you already have a project and want to add Ash to it, Igniter provides a convenient way:

$ mix igniter.install ash

This will add Ash to your dependencies and set up the necessary configuration files. If you need PostgreSQL support, you can run:

$ mix igniter.install ash_postgres

Igniter will guide you through the process, showing you the changes it will make and asking for confirmation before applying them.

Version pin at the time of writing

Ash 3.x is still a moving target. The examples in this book were verified against the following versions:

  • ash ~> 3.24 (3.24.3 at the time of writing)

  • ash_postgres ~> 2.9 (2.9.0 at the time of writing)

  • ash_phoenix ~> 2.3

  • igniter_new ~> 0.5 (the archive, plus igniter as a dep)

Igniter pins to whatever is current when you run mix igniter.new, which means new projects will usually be one minor version ahead of what you see printed here. The public API has been stable since 3.0, so the examples should work without change. If a specific iex line fails, the most likely culprit is a renamed helper, not a broken example; mix ash --help is a good next step.