---
title: Workspaces
description: Use workspaces to organize your turborepo apps and packages.
---

import Callout from "../../../components/Callout";
import HeartIcon from "@heroicons/react/solid/HeartIcon";
import { Tabs, Tab } from '../../../components/Tabs'

# Getting started with workspaces

Workspaces are a feature implemented by package managers to assist with working on multiple apps and packages in the same codebase.

Turborepo is compatible with three package managers, [npm](https://docs.npmjs.com/cli/v8/using-npm/workspaces#description), [Yarn](https://classic.yarnpkg.com/lang/en/docs/workspaces/), and [pnpm](https://pnpm.io/workspaces), each with its own implementation of workspaces and functionality. Your package manager will determine how your apps and packages are organized in your workspaces and run in your turborepo.

## Configuring workspaces

To use workspaces, you'll first need to declare their file system locations to your package manager

A common/recommended convention is to have an `apps` folder and a `packages` folder. The `apps` folder can contain workspaces for launchable apps, such as a Next.js or Svelte app. The `packages` folder can contain workspaces for packages that are used by either an app, or another package. Again, this isn't a requirement, but just a suggested folder structure

<Callout>
Unlike when working in a single-package repository, you'll need to consider how to name your workspaces. If you avoid npm naming collisions, you can use an npm organization or user scope to namespace your packages. For example, you might set the `name` key in `./apps/api/package.json` to `@mycompany/api`.
</Callout>

<Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager">
  <Tab>

    Add the folders you want to configure as workspaces to the `workspaces` field in your root `package.json` file. This field contains a list of workspace folders in the form of globs:

    ```json
    {
      "name": "monorepo",
      "version": "1.0.0",
      "workspaces": [
        "docs",
        "apps/*",
        "packages/*"
      ]
    }
    ```

  </Tab>
  <Tab>

    Add the folders you want to configure as workspaces to the `workspaces` field in the root `package.json` file. This field contains a list of workspace folders in the form of globs:

    ```json
    {
      "name": "monorepo",
      "version": "1.0.0",
      "workspaces": [
        "docs",
        "apps/*",
        "packages/*"
      ]
    }
    ```

  </Tab>

  <Tab>

    Add the folders you want to configure as workspaces to the `pnpm-workspace.yaml` file that exists in your root directory. This file contains a list of workspace folders in the form of globs:

    ```yaml
    packages:
      - "docs"
      - "apps/*"
      - "packages/*"
    ```

  </Tab>
</Tabs>

Each folder that matches any of the globs in the list is considered a workspace folder. In the examples, the `apps` and `packages` folders contain folders that are workspaces, and the `docs` folder itself is a workspace.

```
monorepo/
├─ docs/
├─ apps/
│  ├─ api/
│  ├─ mobile/
├─ packages/
│  ├─ tsconfig/
│  ├─ config/
├─ sdk/
```

Using the same workspace configuration, the `monorepo/docs/`, `monorepo/apps/api/`, `monorepo/apps/mobile/`, `monorepo/packages/config/`, and `monorepo/packages/tsconfig/` folders are all considered workspaces.
The `monorepo/sdk/` folder is not considered a workspace and it is not included in the workspace configuration.

## Managing workspaces

When you move, delete, or rename your workspaces, you will have to make sure that all folders linked within your `package.json` matches. Anytime you change the configuration of your workspace, make sure all the dependencies of the workspace are also updated. Re-run your npm client's install command to check your configuration. If there are any problems after that, you may have to delete your `node_modules` folder and run an install again.

## Managing dependencies

To manage dependencies within workspaces in your monorepo, you will need to run commands that will only manage the dependencies of each workspace rather than for the entire monorepo.

<Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager">
  <Tab>

    **Install**
    ```bash
    npm install <package> -w=<workspace>
    ```

    Example:
    ```bash
    npm install react -w=web
    ```

    **Uninstall**
    ```bash
    npm uninstall <package> -w=<workspace>
    ```

    Example:
    ```bash
    npm uninstall react -w=web
    ```

    **Update**
    ```bash
    npm update <package> -w=<workspace>
    ```

    Example:
    ```bash
    npm update react -w=web
    ```

  </Tab>
  <Tab>

    **Install**
    ```bash
    yarn workspace <workspace> add <package>
    ```

    Example:
    ```bash
    yarn workspace web add react
    ```

    **Uninstall**
    ```bash
    yarn workspace <workspace> remove <package>
    ```

    Example:
    ```bash
    yarn workspace web remove react
    ```

    **Update**
    ```bash
    yarn workspace <workspace> upgrade <package>
    ```

    Example:
    ```bash
    yarn workspace web upgrade react
    ```

  </Tab>
  <Tab>

    **Install**
    ```bash
    pnpm add <package> --filter <workspace>
    ```

    Example:
    ```bash
    pnpm add react --filter web
    ```

    **Uninstall**
     ```bash
    pnpm uninstall <package> --filter <workspace>
    ```

    Example:
    ```bash
    pnpm uninstall react --filter web
    ```

    **Update**
     ```bash
    pnpm up <package> --filter <workspace>
    ```

    Example:
    ```bash
    pnpm up react --filter web
    ```

  </Tab>
</Tabs>
