Table of Contents

• Project Status
• Requirements
• Features
  • Packages
    • phx_new
    • livebook
• Usage
  • Via Flake Template
  • Manually Via flake-parts
• Setting Versions
  • Explicitly
  • .tool-versions Compatibility
• Future Plans
• Contributing
  • Newly-published language versions
  • Other Beam Languages
  • Other Details
• Credits

• Nix with Flakes support
• flake-parts
• direnv (Optional)

• Automatic packaging for ~any finalized, tagged release of both Erlang/OTP and Elixir
  • Package definitions are based on upstream nixpkgs definitions with src overrides
  • Packages will be added to your own flake's outputs, and can be consumed by other Nix code
• Declarative, automatic devShell creation using these packages (with opt-out)
  • Opt-in support for elixir-ls and erlang_ls LSP servers
• Elixir-ecosystem-aware Nix helpers
• A small number of Elixir applications usable directly via nix run (see below)
• Flake Templates

Want to start a new Phoenix project? Don't have a global install of Elixir/Mix? This can help. Pairs well with flake templates below.

nix run github:shanesveller/nix-beam-flakes#phx_new -- --help

nix run github:shanesveller/nix-beam-flakes#livebook -- server

nix flake init -t github:shanesveller/nix-beam-flakes#default
# or
nix flake init -t github:shanesveller/nix-beam-flakes#phoenix

At the time of writing there is no meaningful distinction between the two, but they will diverge as I continue to implement speciality support for the needs of a Phoenix project.

Please review the documentation for flake-parts here if you are new to this library/paradigm.

A complete example:

{
  description = "My Elixir application";

  inputs = {
    beam-flakes.url = "github:shanesveller/nix-beam-flakes";
    beam-flakes.inputs.flake-parts.follows = "flake-parts";
    flake-parts.url = "github:hercules-ci/flake-parts";
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  };

  outputs = {
    self,
    beam-flakes,
    flake-parts,
    ...
  }:
    flake-parts.lib.mkFlake {inherit self;} {
      imports = [beam-flakes.flakeModule];

      systems = ["aarch64-darwin" "x86_64-darwin" "x86_64-linux"];

      perSystem = _: {
        beamWorkspace = {
          enable = true;
          devShell.languageServers.elixir = true;
          versions = {
            elixir = "1.16.2";
            erlang = "26.2.3";
          };
        };
      };
    };
}

You can add any additional packages to perSystem.beamWorkspace.devShell.extraPackages. You can provide additional arguments to mkShell, such as arbitrary environment variables, via perSystem.beamWorkspace.devShell.extraArgs. You can opt out of the automatic default devShell and manage yourself by setting perSystem.beamWorkspace.devShell.enable = false;

    flake-parts.lib.mkFlake {inherit self;} {
      # ...
      perSystem = _: {
        beamWorkspace = {
          versions = {
            # You can also use an `asdf`-compatible string, such as "1.14.2-otp-25".
            #
            # Everything after the first hyphen is stripped and handled according
            # to the defined erlang version instead.
            elixir = "1.16.2";
            erlang = "26.2.3";
          };
        };
      };
    };

For projects that formerly, or concurrently, use asdf, a compatibility shim will read your .tool-versions file and set the elixir and erlang versions accordingly.

    flake-parts.lib.mkFlake {inherit self;} {
      # ...
      perSystem = _: {
        beamWorkspace = {
          enable = true;
          versions = {
            fromToolVersioons = ./.tool-versions;
          };
        };
      };
    };

Immediate concerns:

• Significant documentation efforts inspired by the flake-parts website
• CI that the modules continue to evaluate successfully with common scenarios
• A binary cache for the latest pairing of Erlang/Elixir for MacOS/Linux
• More robust specialty support for Phoenix projects

Later on:

• Expose/enforce the compatibility-check logic that honors Elixir's compatibility policy so flake users get immediate feedback when they've chosen an unsupported combination
• Phoenix speciality support
  • esbuild binaries
  • tailwind binaries
  • Possibly some lightweight Node.js support

Future:

• pre-commit-hooks.nix integration with canned Elixir-specific hooks - it already pairs nicely using the flake-parts module
• Automatic Docker-compatible OCI image creation from your Mix release via pkgs.ociTools
• NixOS module generation to run your Mix release via systemd

Generally not solicited at this time, but if you're particularly adventurous, read on.

If you are a Nix user, this is already automated:

nix develop ./dev
just add-elixir 1.16.2
just add-erlang 26.2.3

Just PR the changes to data that it committed for you. I'll probably be on top of it already, for the most part.

At this time I am not a personal or professional user of any other languages that inhabit the BEAM VM, and I do not feel I can offer a satisfactory level of support or nuance for tooling I do not use. As such, I will consider collaborating with those who do to offer support here on a best-effort basis, but I do not consider it a priority at this time.

Please open an issue/discussion before setting out on any other contributions so that we can discuss whether your ideas align with my plans for this project. I'd hate to see anyone feel like their effort/goodwill were wasted.

I would not have pushed this very far were it not for flakes and flake-parts. I've gotten several rounds of useful feedback directly from discussions on the flake-parts repository as well as learned a lot from studying its code.

I also take some inspiration from oxalica/rust-overlay.