---
title: Getting started
description: >-
  Activate Melos, add it to the root `pubspec.yaml` file, and bootstrap the
  workspace.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://melos.invertase.dev/llms.txt
> Use this file to discover all available pages before exploring further.

Before you use Melos, complete a few one-time setup steps.

<Steps>
  <Step title="Read the pub workspaces guide">
    Before you set up the repository, read the [pub workspaces guide](https://dart.dev/tools/pub/workspaces).
  </Step>
  <Step title="Activate Melos">
    To use Melos from anywhere on your system, install it as a
    [global package](https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path)
    via [pub.dev](https://pub.dev/):

    ```bash
    dart pub global activate melos
    ```

    <Warning>
      If using Git Bash on Windows, `melos` is not callable directly as it
      has a `*.bat` extension. To call Melos with arguments, you can update your `~/.bash_profile` file with
      the following function:

      ```bash
      function melos() {
        melos.bat $@
      }
      ```
    </Warning>
  </Step>
  <Step title="Create the workspace pubspec">
    If you don't have a `pubspec.yaml` file at the workspace root yet, create one
    now:

    ```yaml
    name: my_project
    publish_to: none
    environment:
      sdk: ^3.9.0
    workspace:
      - packages/helper
      - packages/client_package
      - packages/server_package
    ```

    <Info>
    Starting from Dart v3.11.0, the workspace definition supports globs.
    </Info>

    Where `packages/helper`, `packages/client_package`, and `packages/server_package`
    are the paths to the packages in your workspace.

    Melos is designed to work with a workspace. A workspace is a directory that
    contains all the packages you develop together. Its root
    directory must contain a `pubspec.yaml` file defining the workspace.

    With Melos, the workspace root holds configuration rather than an app or
    package. You can still put a package in the root; Melos supports that.
    When using `useRootAsPackage: true`, it is even required.
    For more information, see [`useRootAsPackage`](/configuration/overview#userootaspackage).

    The following is the recommended workspace directory structure:

    ```console
    my_project
    ├── apps
    │   ├── apps_1
    │   └── apps_2
    ├── packages
    │   ├── package_1
    │   └── package_2
    ├── pubspec.yaml
    └── README.md
    ```

    Different Melos workspaces might use different versions of Melos. The root
    `pubspec.yaml` file includes the `melos` package so everyone in the workspace,
    including continuous integration (CI) jobs, uses the same Melos version. The
    globally installed version of Melos switches to the version specified in the
    `pubspec.yaml` file, if both versions are not the same.

    The corresponding `pubspec.lock` file belongs in the repository, not in `.gitignore`.
  </Step>
  <Step title="Add Melos to the workspace">
    Add Melos as a development dependency by running the following command:

    ```bash
    dart pub add melos --dev
    ```
  </Step>
  <Step title="Mark each package as a workspace member">
    In each package `pubspec.yaml` file, add the `resolution: workspace` field:

    ```yaml
    name: my_package
    resolution: workspace

    # ...
    ```
  </Step>
  <Step title="Bootstrap the workspace">
    Bootstrap the workspace. Bootstrapping has
    three primary functions:

    - Installing all package dependencies (internally using `pub get`).
    - Syncing shared dependencies between packages.
    - Running any bootstrap lifecycle scripts.

    Bootstrap your project by running the following command:

    ```bash
    melos bootstrap
    ```

    For more information about bootstrapping, see the
    [Bootstrap section](/reference/commands/bootstrap).
  </Step>
</Steps>

## Single package projects (non-monorepo)

A repository with one application or package uses a different `pubspec.yaml` file. For more information about single package projects, see [Single package projects](/getting-started/single-package).

## Next steps

After you bootstrap the workspace, you can change a package and
use that change in the packages that depend on it.

Melos also provides other helpful features such as running scripts across all
packages. For example, to run the Dart analyzer in each package, add a new `script`
item in your root `pubspec.yaml` file:

```yaml
name: my_workspace

# ...

melos:
  scripts:
    generate:
      run: melos exec -c 1 --depends-on build_runner -- dart run build_runner build
```

Then run that script with `melos generate`.

For more information about scripts, see [Scripts](/configuration/scripts).
For inspiration, see the
[FlutterFire](https://github.com/firebase/flutterfire/blob/main/pubspec.yaml)
or [Flame](https://github.com/flame-engine/flame/blob/main/pubspec.yaml)
repository.

If you are using Visual Studio Code (VS Code), there is a [VS Code extension](/ide-support#vs-code)
available, to integrate Melos with VS Code.