Glossary / Workspace packages

Workspace packages

Workspace packages are local packages managed as part of a multi-package repository by a package manager. They let applications depend on sibling libraries through package names while developers edit and build those packages together, but local linking can differ from how a published tarball is installed.

Declaration and linking

npm and Yarn commonly declare workspace globs in the root package.json; pnpm uses pnpm-workspace.yaml (and can import patterns from package.json during setup). Package managers link matched package folders into the dependency graph. The workspace: protocol, supported by pnpm and modern Yarn and by npm in current releases for workspace resolution in relevant contexts, can require a local package; check exact manager-version semantics. A normal semver range may resolve locally when a matching workspace exists depending on manager policy.

Workspace packages still need their own manifests and declared dependencies. Root-level hoisting can hide missing declarations, and source imports may work in a workspace while the published package is missing built files, declarations, or exports. file: dependencies, symlink behavior, and peer dependencies can also differ from registry installation.

Engineering guidance

Keep package boundaries explicit, use workspace protocols intentionally, and test packed artifacts with a consumer fixture. Build dependencies in topological order and verify exports, files, and declarations. Use workspace filtering to target commands while preserving needed dependency tasks.

Interview questions

  1. What is a workspace package? A local package participating in a package manager's multi-package project.
  2. Why use package names instead of relative source paths? It exercises package boundaries and resolution closer to consumer use.
  3. What does workspace: communicate? Resolve a local workspace package under manager-specific semantics.
  4. Why test the packed tarball? Workspace links can expose files and dependencies absent from the published package.
  5. What is a phantom dependency risk? Hoisting makes an undeclared import resolve locally but not for consumers.

References