Link Workspace Packages
Developmentlink-workspace-packagesLink Workspace Packages is an Agent Skill for development published in the tsparticles/tsparticles repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Link workspace packages in monorepos (npm, yarn, pnpm, bun). USE WHEN: (1) you just created or generated new packages and need to wire up their dependencies, (2) user imports from a sibling package and needs to add it as a dependency, (3) you get resolution errors for workspace packages (@org/*) like "cannot find module", "failed to resolve import", "TS2307", or "cannot resolve". DO NOT patch around with tsconfig paths or manual package.json edits - use the package manager's workspace commands to fix actual linking.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/tsparticles/tsparticles/blob/HEAD/.cursor/skills/link-workspace-packages/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/link-workspace-packages, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Link Workspace Packages
Add dependencies between packages in a monorepo. All package managers support workspaces but with different syntax.
Detect Package Manager
Check whether there's a packageManager field in the root-level package.json.
Alternatively check lockfile in repo root:
pnpm-lock.yaml→ pnpmyarn.lock→ yarnbun.lock/bun.lockb→ bunpackage-lock.json→ npm
Workflow
- Identify consumer package (the one importing)
- Identify provider package(s) (being imported)
- Add dependency using package manager's workspace syntax
- Verify symlinks created in consumer's
node_modules/
pnpm
Uses workspace: protocol - symlinks only created when explicitly declared.
# From consumer directory
pnpm add @org/ui --workspace
# Or with --filter from anywhere
pnpm add @org/ui --filter @org/app --workspace
Result in package.json:
{ "dependencies": { "@org/ui": "workspace:*" } }
yarn (v2+/berry)
Also uses workspace: protocol.
yarn workspace @org/app add @org/ui
Result in package.json:
{ "dependencies": { "@org/ui": "workspace:*" } }
npm
No workspace: protocol. npm auto-symlinks workspace packages.
npm install @org/ui --workspace @org/app
Result in package.json:
{ "dependencies": { "@org/ui": "*" } }
npm resolves to local workspace automatically during install.
bun
Supports workspace: protocol (pnpm-compatible).
cd packages/app && bun add @org/ui
Result in package.json:
{ "dependencies": { "@org/ui": "workspace:*" } }
Examples
Example 1: pnpm - link ui lib to app
pnpm add @org/ui --filter @org/app --workspace
Example 2: npm - link multiple packages
npm install @org/data-access @org/ui --workspace @org/dashboard
Example 3: Debug "Cannot find module"
- Check if dependency is declared in consumer's
package.json - If not, add it using appropriate command above
- Run install (
pnpm install,npm install, etc.)
Notes
- Symlinks appear in
<consumer>/node_modules/@org/<package> - Hoisting differs by manager:
- npm/bun: hoist shared deps to root
node_modules - pnpm: no hoisting (strict isolation, prevents phantom deps)
- yarn berry: uses Plug'n'Play by default (no
node_modules)
- npm/bun: hoist shared deps to root
- Root
package.jsonshould have"private": trueto prevent accidental publish