Work with Umbrella Applications

Why do we need umbrellas?

Contexts can help us determine how to break our application into more manageable parts. As our applicaiton continues to grow, we may find that we want a greater degree of separation between the components. This can happen if individual contexts start to grow too large or if we’re to deploy different parts of our application separately.

Umbrellas allow us to easily group multiple applications into the same mix project and source code repository. Instead of bundling all of our code into a single application, we can split it up into multiple applications. Elixir’s mix new and Phoenix’s mix phx.new generators support creating umbrella projects by passing the --umbrella flag.

Understand umbrellas

An umbrella project consists of a top-level mix project (usually called the umbrella project) and several sub-projects inside the apps/ directory (usually called child applications).

Note: When working with Elixir and OTP, terminology can get a little confusing, particularly with the words “project” and “application.” In this case, a “project” is something we use to configure and organize the app we’re building, and “application” is an OTP application.

The umbrella project is what we use to configure and organize our application through the mix.exs and config/ files. All of the logic and code that makes the pplication work resides in the child applications.

Usually, a mix project is also an OTP application, but that’s not the case for the top-level umbrella project—only projects inside the apps/ directory are actual OTP applications. This means the umbrella project should only be used for configuring the other applications, and no application code should live inside it.

Split the front-end and back-end

One way to use umbrellas is to split the front-end and back-end logic into separate applications.