A Workspace is a collection of mix projects under the same git repo.

Workspace provides a set of tools for working with multiple projects under the same git repo. Using path dependencies between the projects and the provided tools you can effectively work on massive codebases properly split into reusable packages.

Structuring a folder as a workspace root

A workspace is a normal Mix.Project with some tweaks:

• No actual code is expected, so :elixirc_paths is set to []
• It must have a :workspace project option configured with a :type set to :workspace.

def project do
  [
    workspace: [
      type: :workspace,
      # arbitrary options can be set there
    ],
    # rest Mix.Project settings
  ]
end

A generator is provided for bootstrapping a new workspace project:

$ mix workspace.new NAME

Workspace projects

A mix project is considered a workspace project if:

• it is located in a subfolder of the workspace root path
• it is not included in the ignored projects or ignored paths in the workspace config

Assuming the folder structure:

my_workspace
├── apps
│   ├── api         # an API app
│   └── ui          # the UI project
├── mix.exs         # this is the workspace root definition
├── .workspace.exs  # the workspace config
└── packages        # various reusable packages under packages
    ├── package_a
    ├── package_b
    └── package_c

In the above example:

• We have defined a Workspace under my_workspace folder
• All mix projects under my_workspace are by default considered workspace packages. In the above example it will include the :api, :ui, :package_a, :package_b and :package_c packages.

ignore_projects: [:package_a]

ignore_paths: ["other"]

my_workspace
├── apps
│   └── api
├── mix.exs
├── packages
│   ├── package_a  # package_a project defined under packages
│   └── package_b
└── shared
    └── package_a  # redefinition of package_a

Loading a workspace

A Workspace can be constructed by calling the new/2 function. It will use the given path and config object in order to load and validate all internal projects.

The workspace graph

The most important concept of the Workspace is the projects graph. The project graph is a directed acyclic graph where each vertex is a project and each edge a dependency between the two projects.

The workspace graph is constructed implicitly upon workspace's creation in order to ensure that all path dependencies are valid and decorate each project with graph metadata.

mix workspace.graph --workspace-path test/fixtures/sample_workspace

package_a
├── package_b
│   └── package_g
├── package_c
│   ├── package_e
│   └── package_f
│       └── package_g
└── package_d
package_h
└── package_d
package_i
└── package_j
package_k

flowchart TD
package_a
package_b
package_c
package_d
package_e
package_f
package_g
package_h
package_i
package_j
package_k

package_a --> package_b
package_a --> package_c
package_a --> package_d
package_b --> package_g
package_c --> package_e
package_c --> package_f
package_f --> package_g
package_h --> package_d
package_i --> package_j

Workspace filtering

As your workspace grows running a CI task on all projects becomes too slow. To address this, code change analysis is supported in order to get the minimum set of projects that need to be executed.

Workspace supports various filtering modes. Each one should be used in context with the underlying task. For more details check filter/2.

Global filtering options

• :ignored - ignores these specific projects
• :selected - considers only these projects
• :only_roots - considers only the graph roots (sources), e.g. ignores all projects that have a parent in the graph.

Code analysis related options

• :modified - returns only the modified projects, e.g. projects for which the code has changed
• :affected - returns all affected projects. Affected projects are the modified ones plus the

:modified and :affected can be combined with the global filtering options.

flowchart TD
  package_a
  package_b
  package_c
  package_d
  package_e
  package_f
  package_g
  package_h
  package_i

  package_a --> package_b
  package_a --> package_c
  package_a --> package_d
  package_b --> package_g
  package_c --> package_e
  package_c --> package_f
  package_f --> package_g
  package_h --> package_d
  package_i --> package_b

  class package_a affected;
  class package_c affected;
  class package_d modified;
  class package_f modified;
  class package_h affected;

  classDef affected fill:#FA6,color:#FFF;
  classDef modified fill:#F33,color:#FFF;

# We want to build only the top level affected projects
mix workspace.run -t compile --only-roots --affected

# we want to format only the modified ones
mix workspace.run -t format --modified

# we want to test all the affected ones
mix workspace.run -t test --affected

Explicit dependencies

Sometimes you may want to specify explicit dependencies between projects and files that cannot be deduced by the mix dependencies. For example you may have a Rust NIF project which uses a Rust crate also present in your monorepo, or you may require some *.exs files that are shared across the workspace.

In such cases you can use the :affected_by option in the project's workspace config to explicitly define those dependencies. If any of the files defined there is changed, then the project is considered affected.

When workspace status is updated, the system checks if any changed files match the patterns defined in affected_by. If a match is found, the project is marked as :affected and will be included in affected project lists.

# In a project's mix.exs
def project do
  [
    # ... other config
    workspace: [
      affected_by: [
        "../shared/config.ex",           # Specific file
        "../shared/*.ex",                # All .ex files in shared directory
        "../../docs/**/*.md",             # All markdown files in docs including nested directories
        "../shared/",                    # Any file in shared directory
      ]
    ]
  ]
end

Environment variables

The following environment variables are supported:

• WORKSPACE_DEBUG - if set then debug information will be printed.

Environment variables that are not meant to hold a value (and act basically as flags) should be set to either 1 or true, for example:

$ WORKSPACE_DEBUG=true mix workspace.check

Multiple workspaces under the same git repo

You can have multiple workspaces under the same git repo with the only constraint that they cannot be nested.

workspace
├── .workspace.exs
├── another_workspace
│   ├── .workspace.exs
│   └── mix.exs
└── mix.exs

This may be useful if you have a monorepo with various projects that have different dependencies and/or different teams managing them with different policies.

For example, assuming a git repo under my-repo you could create as many workspaces as you wish:

$ cd my-repo
$ mix workspace.new common
$ mix workspace.new backend
$ mix workspace.new frontend/app_a

defmodule Root.MixWorkspace do
  use Mix.Project

  def project do
    [
      app: :root,
      version: "0.2.0",
      elixir: "~> 1.15",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      elixirc_paths: []
    ]
  end

  def application do
    [
      extra_applications: []
    ]
  end

  defp deps do
    [
      {:workspace, "~> 0.2"}
    ]
  end
end

$ mix workspace.list --workspace-path common
$ mix workspace.status --workspace-path frontend/app_a