Elixir Q & A


What is the recommended project structure in Elixir?

Creating a well-organized project structure in Elixir is essential for maintainability, scalability, and collaboration among developers. While Elixir projects are flexible and allow customization, following certain conventions can help ensure a consistent and clear structure. Here’s a recommended project structure for Elixir applications:


  1. `lib/` Directory: This is where the core application code resides. Organize your Elixir modules into subdirectories based on their functionality. For example, you might have `lib/my_app/user.ex` for user-related functionality and `lib/my_app/product.ex` for product-related code.


  1. `test/` Directory: Place your test files in this directory. Elixir’s built-in testing framework, ExUnit, expects test files to be named after the modules they test, such as `my_app_user_test.exs` for testing the `User` module. Organize your tests similarly to your application code, mirroring the structure in the `lib/` directory.


  1. `config/` Directory: Store configuration files here, such as environment-specific configuration files (e.g., `dev.exs`, `prod.exs`) and application-specific configuration files (e.g., `my_app.exs`). Use these files to define settings like database connections, external service URLs, and application-specific variables.


  1. `priv/` Directory: Include any private files required by your application, such as binary assets, templates, or static files. These files aren’t meant to be compiled directly into the application but are accessible at runtime.


  1. `deps/` Directory: This directory is managed by Mix, Elixir’s build tool, and contains project dependencies. You don’t need to manually organize files in this directory.


  1. `_build/` Directory: Also managed by Mix, this directory holds build artifacts, including compiled code and test results. It’s automatically created and shouldn’t be modified manually.


  1. `assets/` Directory: If your application includes a frontend component (e.g., using Phoenix LiveView or Nerves), place frontend assets and code in this directory. It’s a common convention for web applications.


  1. `doc/` Directory: Generate and store documentation files here using tools like ExDoc. Good documentation is crucial for understanding your application’s APIs and behavior.


  1. `rel/` Directory: If your project needs to be packaged as a release, you can configure release-specific settings and scripts in this directory.


  1. `mix.exs`: The project configuration file where you define project metadata, dependencies, and application-specific settings.


  1. ‘README.md`: A README file providing essential information about your project, including its purpose, setup instructions, and usage guidelines.


  1. `LICENSE`: Include a license file to specify how others can use your code legally.


By adhering to this recommended project structure, you’ll make it easier for your team to collaborate, maintain, and scale your Elixir applications effectively. Additionally, following conventions can also help newcomers quickly understand your project’s layout and organization.


Previously at
Flag Argentina
time icon
Tech Lead in Elixir with 3 years' experience. Passionate about Elixir/Phoenix and React Native. Full Stack Engineer, Event Organizer, Systems Analyst, Mobile Developer.