Organising your Elixir project with Mix

We have already covered a lot of ground so far in this exploration of Elixir, but in just about every example we’ve been running our Elixir code either in iex or from a single file.

This is fine for getting to grips with the language and for very simple examples, but we’re going to need something else if we want to manage more complex projects.

In Elixir the answer to this problem is Mix.

Mix is a set of tools for creating, testing, and building your application. It will also handle your dependencies and it is packaged with the language.

In today’s tutorial we are going to be looking at using Mix to manager our Elixir projects.

What is Mix?

When it comes to building applications, there are certain tools that greatly increase your developer productivity. In most languages, these tools are often built by the community, but they are usually as important as the language itself.

Mix is a set of tools for creating, testing, and building your Elixir application. If you are coming from a Ruby background, you can think of Mix as a combination of Rake, Bundler, and Ruby Gems.

You will use Mix to create a new Elixir project, manage it’s dependencies, and compile it ready for deployment.

Mix also deals with including your code from .ex files from folders in the lib directory. And it can also help you split code into “Umbrella Projects”.

Another interesting aspect of Mix is that it ships with ExUnit, a testing framework. And so when you create a new Mix project, you’ve already got everything you need to start building an Elixir application.

If you have Elixir installed on your computer you already have Mix installed as it is shipped as part of the language.

Creating a new project

One of the first things you will need Mix for is to create yourself a new project. Run the following in your terminal:

mix new hello
[/bash]
This will create a new directory called `hello` with a number of files and directories that form the convention of an Elixir project.
Using a command line tool for creating a new project is a much better way than copying the files and structure from a previous project (or a tutorial like this) and it will save you a lot of headache when you inevitably make a small mistake.
Mix will also automatically generate a `.gitignore` and a `README.md` so you have already got everything you need to get going with your new project.
Under the `config` directory you will find a `config.exs` file for setting any configuration options you might have.
Under the `lib` directory is where you will put the code of your application. You will see that Mix has automatically created a new file named using the identifier you provided Mix when creating the application, in my case `hello.ex`:
```elixir
defmodule Hello do
end

And finally you have a test directory which is where you will write your tests. I’ll speak more about writing tests later in this article.

Naming conventions of Mix applications

Up until this point we have mostly been writing code in iex or stuffing all of our code into a single file.

Mix allows you to structure your code in a more organised fashion, and it will deal with loading your code correctly when the application is complied.

There are a couple of naming conventions that you would stick to:

Use a top level module to prevent naming collisions

Each module should be in a single file, and each file should have a single module

File names should be snake cased

Module names should be camel cased

The folder structure should mirror the module names

Writing tests

Writing tests is a really important part of building high quality applications and so Elixir ships with a testing framework as part of the language.

When you generated your new Mix project, a test directory was created with files named test_helper.exs and hello_test.exs.

The test_helper.exs file is where you can set up any configuration type stuff you might need for your tests, and the hello_test.exs file is automatically generated as a place to write tests for your top level module:

defmodule HelloTest do
use ExUnit.Case
doctest Hello
test "the truth" do
assert 1 + 1 == 2
end
end

As you can see, we already have a test that was generated by Mix and so we can run the tests to see them pass. Run the following command in terminal to run the tests:

mix test
[/bash]
You can also run your tests with the `--trace` flag to see a more detailed report:
```bash
mix test –trace
[/bash]
We will be taking a much deeper dive into testing with Elixir and ExUnit in a future article so I won’t go into any more detail at this stage.
## Compiling and Running in iex
Once you’ve written some code you will probably want to compile it and play with it in `iex` to see if it’s working as it should be.
For the sake of demonstration purposes, lets add a simply function to the `Hello` module:
```elixir
defmodule Hello do
def greet do
IO.puts("Hello World")
end
end

To compile the project you would run the following command in terminal:

mix compile
[/bash]
This will create a new directory called `_build` that will contain the compiled `.beam` files.
You can also compile and load your application into `iex` so you can play with it from the command line. To do that you would run the following command in terminal:
```bash
iex -S mix
[/bash]
This will drop you into `iex` with your code compiled and ready to go.
## What are Umbrella Projects?
One of the most interesting aspects of Mix is the functionality to create “Umbrella Projects”.
In Elixir, an application is a set of modules that can be started and stopped as one. The Erlang virtual machine encourages you to split your code up into independent applications.
You can think of each application as a “micro service”, and so a typical web application might be comprised of many independent Elixir applications.
Mix makes it easier to manage these independent Elixir applications through umbrella projects.
An umbrella project allows you to manage all of your Elixir applications under one repository. This enables you to compile and test as one project, or as independent applications, getting the best of both micro services and monolith architectures.
To create an umbrella project you would use the `--umbrella` flag when creating a new project:
```bash
mix new killer_app –umbrella
[/bash]
This will create a simplified version of the normal project structure we looked at earlier.
Inside of an umbrella project you will find an `apps` directory. In this directory is where you would run the `mix new` command for each of the applications of your project.
Mix will automatically detect that you are running this command from within an umbrella project and it will automatically configure the generated applications correctly for you.
## Conclusion
Mix is one of the many reasons why developer experience is so good with Elixir. It provides all of the tools you will need to get started writing, building, and testing your Elixir project. And it all comes as part of the language so you don’t need to set it up for yourself.
Probably one of the most interesting aspects of Elixir projects is how umbrella projects work. When I realised that this was possible, suddenly a lot of the practical considerations of building a micro services application began to fall into place.
As we continue to explore the world of building Elixir applications we will no doubt cover many of the edge cases of using Mix. But hopefully that was a good introduction to what you can expect from the Elixir tool belt.