Learning Elixir: Project Structure

When an Elixir project outgrows a handful of modules, the habit of pasting definitions into IEx starts to break down — redefinition warnings pile up, names collide, and nothing survives the session. One way to picture what comes next is a workshop: it begins as a single shelf of drawers and, as the work grows, turns into a whole room with labeled aisles and a storage room for materials that are not tools at all. In the last few articles I filled those drawers — modules — and learned how to reach between them with alias , import , and require . A project structure is the map of that room: it tells me where each module lives on disk, how file names line up with module names, and which aisles other people are allowed to walk into. In this article, we will build a real Mix project from scratch and watch it grow: starting from mix new , adding directories like lib , test , priv , and config , naming modules so they mirror their paths, and drawing boundaries so the project stays navigable as it grows. Note : The examples in this article use Elixir 1.20.1. While most operations should work across different versions, some functionality might vary. This is also a small turning point for the series: instead of pasting examples into iex , everything from now on lives in real files inside a Mix project. Each code block shows the file path, and every example is verified with mix run , with the output shown right after — and when we just want to poke at our functions, iex -S mix brings back the interactive shell, now with the project compiled from its files. Table of Contents Introduction Starting From Mix New The Anatomy of the Default Project Growing Lib: Modules That Mirror Paths Running the Project: Scripts and the Shell Namespaces and Boundaries The Priv Directory Configuration and Environments Practical Guidelines Conclusion Further Reading Next Steps Introduction In the previous articles, every example was self-contained: one or two defmodule blocks pasted into an iex sess