View Source Library guidelines

This document outlines general guidelines for those writing and publishing Elixir libraries meant to be consumed by other developers.

Getting started

You can create a new Elixir library by running the mix new command:

$ mix new my_library

The project name is given in the snake_case convention where all letters are lowercase and words are separate with underscores. This is the same convention used by variables, function names and atoms in Elixir. See the Naming Conventions document for more information.

Every project has a mix.exs file, with instructions on how to build, compile, run tests, and so on. Libraries commonly have a lib directory, which includes Elixir source code, and a test directory. A src directory may also exist for Erlang sources.

For more information on running your project, see the official Mix & OTP guide or Mix documentation.

Applications with supervision tree

The mix new command also allows the --sup option to scaffold an application with a supervision tree out of the box. We talk about supervision trees later on when discussing one of the common anti-patterns when writing libraries.

Publishing

Writing code is only the first of many steps to publish a package. We strongly recommend developers to:

  • Choose a versioning schema. Elixir requires versions to be in the format MAJOR.MINOR.PATCH but the meaning of those numbers is up to you. Most projects choose Semantic Versioning.

  • Choose a license. The most common licenses in the Elixir community are the MIT License and the Apache License 2.0. The latter is also the one used by Elixir itself.

  • Run the code formatter. The code formatter formats your code according to a consistent style shared by your library and the whole community, making it easier for other developers to understand your code and contribute.

  • Write tests. Elixir ships with a test-framework named ExUnit. The project generated by mix new includes sample tests and doctests.

  • Write documentation. The Elixir community is proud of treating documentation as a first-class citizen and making documentation easily accessible. Libraries contribute to the status quo by providing complete API documentation with examples for their modules, types and functions. See the Writing documentation chapter of the Getting Started guide for more information. Projects like ExDoc can be used to generate HTML and EPUB documents from the documentation. ExDoc also supports "extra pages", like this one that you are reading. Such pages augment the documentation with tutorials, guides, references, and even cheat-sheets.

  • Follow best practices. The Elixir project documents a series of anti-patterns that you may want to avoid in your code. The process-related anti-patterns and meta-programming anti-patterns are of special attention to library authors.

Projects are often made available to other developers by publishing a Hex package. Hex also supports private packages for organizations. If ExDoc is configured for the Mix project, publishing a package on Hex will also automatically publish the generated documentation to HexDocs.

Dependency handling

When your library is published and used as a dependency, its lockfile (usually named mix.lock) is ignored by the host project. Running mix deps.get in the host project attempts to get the latest possible versions of your library’s dependencies, as specified by the requirements in the deps section of your mix.exs. These versions might be greater than those stored in your mix.lock (and hence used in your tests / CI).

On the other hand, contributors of your library, need a deterministic build, which implies the presence of mix.lock in your Version Control System (VCS).

The best practice of handling mix.lock file therefore would be to keep it in VCS, and run two different Continuous Integration (CI) workflows: the usual deterministic one, and another one, that starts with mix deps.unlock --all and always compiles your library and runs tests against latest versions of dependencies. The latter one might be even run nightly or otherwise recurrently to stay notified about any possible issue in regard to dependencies updates.