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

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.

# 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

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