Library guidelines — Elixir v1.16.3

Search documentation of Elixir

# 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.

← Previous Page Compatibility and deprecations
Next Page → Naming conventions