oriz.in / knowledge
type: runbook
status: active
timestamp: 2026-06-21
tags: [runbook, install, workspace, pnpm, submodule, bootstrap]

Install + bootstrap the umbrella workspace

Umbrella workspace clone + bootstrap procedure

Install + bootstrap the umbrella workspace

When to use

You’re a human or agent landing in this repo for the first time, OR your existing clone is out of date. The umbrella repo (chirag127/workspace, cloned at c:/D/oriz/) is a meta-repo containing dozens of git submodules — sites, apps, packages, APIs, extensions, skills.

Golden rule: the user always works from c:/D/oriz/. Never cd into a submodule for install / dev / test commands; always run them from master with pnpm -F <name> or pnpm -r.

Fresh clone

git clone --recurse-submodules https://github.com/chirag127/workspace c:/D/oriz
cd c:/D/oriz
pnpm install -r

That’s it. --recurse-submodules clones every submodule. pnpm install -r recursively installs every package in the pnpm workspace defined by with hoisted deps and a single shared node_modules/.

Existing clone update

cd c:/D/oriz
git pull
git submodule update --init --recursive --remote
pnpm install -r

--remote pulls each submodule to its remote main’s latest, not just the SHA recorded in the master pointer. Use git submodule update --init --recursive (without --remote) to pin to the recorded master pointer SHAs instead. Default to --remote when picking up new work; pin to recorded SHAs only when you specifically want the master’s frozen state.

Run any app

# from c:/D/oriz/ — never from inside the submodule
pnpm -F <package.json#name> dev
pnpm -F <package.json#name> build
pnpm -F <package.json#name> test

The <package.json#name> is the "name" field of the app’s package.json (e.g., @chirag127/oriz-pdf-tools). Use the npm name, NOT the folder slug.

Run all apps or all packages in parallel

pnpm -r --parallel dev          # every app in dev mode (rare; usually one at a time)
pnpm -r build                   # build every workspace member
pnpm -r --parallel test         # test everything in parallel
pnpm -r --parallel typecheck    # typecheck everything in parallel

After adding a new submodule

cd c:/D/oriz
git submodule add --name "projects_<category>_<slug>" \
  "https://github.com/chirag127/<slug>.git" \
  "repos/<category>/<slug>"
git commit -m "feat: add <slug> as submodule"
pnpm install -r

pnpm-workspace.yaml already includes glob patterns for every category dir, so a new submodule auto-joins the workspace if it sits in one of these:

If you add a new category, also update .

After landing changes inside a submodule

cd c:/D/oriz/repos/<category>/<slug>
# ... make changes, commit, push to its own repo's main ...

# Back at master, bump the submodule pointer
cd c:/D/oriz
git add repos/<category>/<slug>
git commit -m "chore: bump <slug> submodule pointer"
git push

Troubleshooting

SymptomCauseFix
pnpm install fails with Cannot find module '@chirag127/<name>'Submodule not initialisedgit submodule update --init --recursive --remote
Submodule folder is empty--recurse-submodules not used during cloneRun the existing-clone update steps above
Failed to resolve workspace dependencyNew submodule not in pnpm-workspace.yaml globsAdd the dir glob to pnpm-workspace.yaml, rerun pnpm install -r
git status shows uncommitted submodule changesWorking inside a submodule edited itcd <submodule> && git status to see; commit there first, then bump pointer at master
Windows: Device or resource busy on rm -rf <submodule-dir>VS Code / editor has a file handle openClose the IDE on that dir, OR git rm --cached <path> + delete from disk next session

Cross-refs

Edit on GitHub · Back to index