We are open sourcing workspace a set of tools for working with elixir monorepos, inspired by rust workspaces and nx.dev. Twitter announcement

You can find the docs here.

There are many reasons for having a monorepo but working with them may be cumbersome. Workspace provides a set of tools for working with big monorepos efficiently.

What is a workspace?

A workspace is nothing more than a git repository hosting multiple mix projects in any arbitrary folder structure. Path dependencies are used for cross project dependencies similarly to umbrellas.

The central concept of the workspace is the workspace graph. This is a directed acyclic graph where the nodes represent projects and the edges the dependencies between projects.

Pasted image 20240513130226409×152 8.38 KB

Workspace uses git to get the changes between two revisions. Knowing which files have changed we can deduce which project is modified or affected:

Running tasks

You can run any command from the root on all or a subset of the workspace projects. You can also run time consuming tasks only on the affected projects significantly improving CI times for large codebases.

Checking your workspace

When your workspace grows, it can go out of hand quickly. You need a way to check that your projects are properly defined. With the workspace.check task you can among other:

• Ensure that specific dependencies are set on all projects, e.g. ex_doc.
• Ensure that external dependencies versions match the expected ones.
• Verify that no forbidden dependencies are defined.
• Ensure that all projects have common build paths

Pasted image 20240513174604816×158 26.5 KB

Enforcing boundaries

One of the main purposes of monorepos is to help you split your codebase into independent, cohesive and reusable packages. You can enforce a clean architecture by tagging your projects and enforcing boundaries between them.

Creating a workspace

You can create a new workspace with the workspace.new scaffolder:

mix archive.install hex workspace_new

mix workspace.new your_workspace

Pasted image 20240513133314530×340 20.3 KB

Helper packages

The workspace repo is itself a workspace and comes with two extra small packages.

• cli_options - provides an opinionated way to parse CLI options based on a schema similarly to NimbleOptions
• cascade - is a small library for generating code for templates.

Disclaimer

Despite being stable (we successfully use it internally to manage a massive elixir codebase consisting of hundreds of packages) this is still a 0.x.x project and breaking changes may happen.