#Glossary

Learn some of the basic terms and primitives of pacwich here.

#Terms

The definitions of workspace and project differ between package managers and monorepo tooling.

#Workspace

In pacwich, the word workspace is closer to how it's used in npm and Bun, a workspace being a nested package in a monorepo.

Not necessarily all packages are workspaces, but all workspaces are packages.

A workspace must have its own package.json file with a unique "name". It is matched via globs you declare with your package manager's config (e.g. the "workspaces" field in your root package.json for Bun or npm, or pnpm-workspace.yaml).

#Project

The project is synonymous with your root where workspaces are defined, often the root of your git repository.

This is where your top-level package.json file is located and where you've defined workspaces for your package manager, whether via the "workspaces" field in package.json (for Bun or npm) or pnpm-workspace.yaml (for pnpm).

pacwich recognizes a project by a root package.json living alongside a lockfile (package-lock.json, bun.lock, pnpm-lock.yaml), since the lockfile is the best source of truth for workspace-related data, so a project and its workspace data aren't recognized or current until you run your install command.

#Script

In the context of pacwich, a script generally refers to an entry in the "scripts" field in a workspace's package.json file by default.

However, pacwich also supports running "inline scripts", one-off shell commands executed from a respective workspace's directory.

#Inputs

Inputs define what items are considered to affect the state of a workspace or the result of a script and are used in determining affected workspaces and the verify feature.

Read more on the Inputs page.

#Terms in Action

This is a minimal example of a project structure for a monorepo. As advertised, pacwich would be able to work in this project without additional setup.

Placing workspaces in the packages/ directory is a common convention but not required.

#File Tree

my-project/
├── package.json
└── packages/
    ├── my-workspace-a/
    |   ├── index.ts
    |   └── package.json
    └── my-workspace-b/
        ├── index.ts
        └── package.json

#Top-level files

The root package.json, using the "workspaces" field if using Bun or npm:

{
  "name": "my-project",
  "workspaces": [
    "packages/*"
  ]
}

If using pnpm, you would have a pnpm-workspace.yaml file instead of using the "workspaces" field in the root package.json above:

# pnpm-workspace.yaml
packages:
  - 'packages/*'

#Workspaces

#my-workspace-a

{
  "name": "my-workspace-a",
  "type": "module",
  "main": "index.ts",
  "scripts": {
    "my-script": "echo 'My script for workspace A'"
  }
}

my-workspace-a's default inputs would be its package.json file, and its index.ts file. If it depended on another workspace, that workspace's inputs would be inherited, and if it had external dependencies (e.g. npm packages), those dependencies' installed versions would be inputs as well.

#my-workspace-b

{
  "name": "my-workspace-b",
  "type": "module",
  "main": "index.ts",
  "scripts": {
    "my-script": "echo 'My script for workspace B'"
  }
}

my-workspace-b's default inputs would be its package.json file, and its index.ts file. If it depended on another workspace, that workspace's inputs would be inherited, and if it had external dependencies (e.g. npm packages), those dependencies' installed versions would be inputs as well.