# Workspaces

Source: https://tapid.dev/docs/workspaces

Configure local package links and select workspace members without losing the root lockfile.

## Version scope

Published v0.0.13 links every discovered workspace member, including members absent from root dependencies, and supports local member cycles. Broad cross-platform workspace-link acceptance remains incomplete. Check the installed binary's version and help before using these examples.

## Declare members

A root manifest can declare member directories and depend on a local package:

```json
{
  "name": "workspace-demo",
  "version": "1.0.0",
  "private": true,
  "workspaces": ["packages/*"],
  "dependencies": { "@example/ui": "workspace:*" }
}
```

Every discovered member is linked under root `node_modules`. Members can depend on one another in cycles. Each member needs a regular `package.json` with a unique name and compatible version. Supported declarations include a string, an array, and an object with a `packages` string or array. Use literal directory paths or whole-component `*` patterns. This is a bounded subset of npm glob matching, not full minimatch support.

Ordinary semver requirements can resolve to a matching local member. `workspace:*`, `workspace:^` and `workspace:~` select a local package using the supported protocol. Missing or incompatible local targets fail before mutation without registry fallback.

## Operate from the root

```bash
$ tapid install
$ tapid add --workspace @example/ui 'is-char@1.1.11'
$ tapid remove --workspace @example/ui is-char
$ tapid prune --workspace @example/ui
$ tapid install --offline --frozen
```

Run from the root or select it with `--project-dir PATH`. Tapid does not search ancestor directories for the root or implicitly select a member from the current directory. `--workspace NAME` takes an exact member package name, not a path or multiple selectors. The root owns `tapid.lock`, store coordination and managed activation; member mutations change the selected member manifest. Install and prune activate the entire workspace graph. Tapid creates neither member locks nor member `node_modules`. Replay checks member manifest digests, identities and dependency edges before rebuilding local links.

A member script runs in its member directory using the root policy and containment boundary:

```bash
$ tapid run test --workspace @example/ui --receipt-json
```

The root `tapid.toml` needs an exact `test` profile. Installation never executes live workspace member lifecycle hooks. Dependency-hook approvals cannot expose live workspace inputs.

## Limits

Different members cannot require incompatible ranges for the same registry package in the published resolver. Nested peer placement, full npm workspace compatibility and broad cross-platform workspace-link validation remain incomplete. Canonical containment checks reject directory escapes and duplicate names, but do not provide race-free protection against concurrent host filesystem replacement.

See the [v0.0.13 compatibility matrix](https://github.com/LimeTip/tapid/blob/v0.0.13/docs/compatibility.md) for published behavior and the remaining workspace acceptance limits.