> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fallow.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Fallow automatically detects monorepo workspaces for npm, yarn, and pnpm. Resolves cross-package imports and supports per-package configuration.

Fallow detects and analyzes monorepo workspaces automatically. It understands npm, yarn, and pnpm workspace protocols, resolves cross-package imports through `node_modules` symlinks, and supports scoping output to a single package.

<Info>
  Workspace detection is automatic. If your repo has a `workspaces` field in `package.json` or a `pnpm-workspace.yaml` file, fallow will find and analyze all packages.
</Info>

## Workspace auto-detection

Fallow detects workspaces from these sources:

| Source                            | Example                              |
| :-------------------------------- | :----------------------------------- |
| `package.json` `workspaces` field | `"workspaces": ["packages/*"]`       |
| `pnpm-workspace.yaml`             | `packages: ["packages/*", "apps/*"]` |

<CodeGroup>
  ```json package.json (npm / yarn) theme={null}
  {
    "workspaces": [
      "packages/*",
      "apps/*"
    ]
  }
  ```

  ```yaml pnpm-workspace.yaml theme={null}
  packages:
    - "packages/*"
    - "apps/*"
  ```
</CodeGroup>

## Cross-workspace imports

When `apps/web` imports from `@myorg/ui`, fallow resolves the import through the `node_modules` symlink back to the workspace source files. Symlinked paths are canonicalized, so usage is tracked against the real source location, not the `node_modules` copy.

```ts apps/web/src/App.tsx theme={null}
// Resolves to packages/ui/src/Button.tsx via node_modules symlink
import { Button } from '@myorg/ui'
```

### Pnpm content-addressable store

Pnpm uses a content-addressable store with a `.pnpm` virtual store inside `node_modules`. Fallow detects these paths and maps them back to the original workspace source files. Cross-package usage is tracked correctly even with pnpm's strict isolation mode.

## Package exports resolution

Fallow resolves the `exports` field in each package's `package.json`, including subpath patterns:

```json packages/ui/package.json theme={null}
{
  "name": "@myorg/ui",
  "exports": {
    ".": "./src/index.ts",
    "./icons": "./src/icons/index.ts",
    "./theme/*": "./src/theme/*.ts"
  }
}
```

An import of `@myorg/ui/icons` resolves to `packages/ui/src/icons/index.ts`.

## Output directory mapping

When a package's `exports` or `main` points to a build output directory (`dist`, `build`, `out`, `esm`, `cjs`), fallow maps it back to the corresponding source file. It tries the same relative path under `src/` with source extensions (`.ts`, `.tsx`, `.js`, `.jsx`).

```json packages/utils/package.json theme={null}
{
  "main": "dist/index.js"
}
```

Fallow maps `dist/index.js` back to `src/index.ts` (or `.js`, `.tsx`, etc.) if the source file exists.

## Per-package tsconfig.json

Fallow discovers `tsconfig.json` files in each workspace package automatically. Path aliases from each package's `tsconfig.json` are used when resolving imports within that package.

```json packages/ui/tsconfig.json theme={null}
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

## Scoping output to workspaces

Use `-w` / `--workspace` to focus on one or more workspaces. Fallow still analyzes the full monorepo graph; only the reported issues are scoped.

Patterns support three forms:

* **Exact package name** or **workspace path**: `web`, `@myorg/ui`, `apps/web`
* **Glob** matched against BOTH the package name AND the workspace path relative to the repo root: `apps/*`, `@scope/*`
* **Negation** with a `!` prefix: `!apps/legacy`

Values can be comma-separated or the flag repeated. Quote patterns containing `!` or glob characters so your shell doesn't expand them.

```bash theme={null}
# Single package (back-compat with earlier fallow versions)
fallow dead-code -w @myorg/ui

# Multiple packages (comma-separated or repeated)
fallow dead-code -w web,admin
fallow dead-code -w web -w admin

# Glob: all apps, all scoped packages
fallow dead-code -w 'apps/*'
fallow dead-code -w '@myorg/*'

# Everything under apps/ except legacy
fallow dead-code -w 'apps/*,!apps/legacy'

# Everything except a workspace (negation only)
fallow dead-code -w '!apps/legacy'
```

```bash title="$ fallow dead-code -w 'apps/*,!apps/legacy'" theme={null}
● Unused exports (2)
  apps/web/src/Button.tsx
    :15 ButtonVariant
  apps/admin/src/Modal.tsx
    :8  ModalContext
  Exported symbols with zero references

✗ 2 issues (31ms, 1,247 files)
```

<Tip>
  For CI matrix jobs, combine `--workspace` with `--changed-since`: fallow intersects the two filters so you analyze only changed files inside the matched workspaces.
</Tip>

## Additional workspace patterns

If fallow doesn't detect all your workspace packages automatically, add extra patterns in your config:

<CodeGroup>
  ```jsonc .fallowrc.json theme={null}
  {
    "workspaces": {
      "patterns": ["tools/*", "shared/*"]
    }
  }
  ```

  ```toml fallow.toml theme={null}
  [workspaces]
  patterns = ["tools/*", "shared/*"]
  ```
</CodeGroup>

These patterns are additive. They extend whatever fallow already detects from `package.json` or `pnpm-workspace.yaml`.

## See also

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration/overview">
    Full config file reference including all available fields.
  </Card>

  <Card title="fallow dead-code" icon="terminal" href="/cli/dead-code">
    CLI reference for running analysis across workspaces.
  </Card>
</CardGroup>