Professional Monorepo Workflow & Troubleshooting A layer-by-layer diagnostic playbook for workspace roots, dependency ownership, lockfiles, versions, line endings, Git state, and common setup failures.
Professional Monorepo Workflow and Troubleshooting Most setup failures are not mysterious. They are scope errors: wrong directory, wrong executable, wrong workspace root, malformed configuration, or a file that Git is already tracking. This book gives you a repeatable diagnostic sequence.
The six-question diagnostic loop Question Evidence
1. Where am I? Get-Location
2. What files does this directory Get-ChildItem -Force contain?
3. Which executable is actually Get-Command node / pnpm / git running?
4. Which versions are active? node --version / pnpm --version / git --version
5. Does pnpm see the expected pnpm run workspace:list workspace?
6. What does Git think changed? git status / git diff / git diff --staged
Problem - command run from the wrong directory Symptom: pnpm cannot find the expected workspace, package.json, or script. Diagnosis:
Get-Location
Get-ChildItem -ForceCorrection: move to the directory containing the intended package.json or workspace root. Do not reinstall pnpm.
Problem - ERR_PNPM_ADDING_TO_ROOT Symptom: pnpm warns that a dependency is being added to the workspace root. This warning is a decision checkpoint, not a failure to suppress. • If the dependency belongs to apps/web, install it in or target apps/web. • If it belongs to apps/api, install it there. • If it truly coordinates the entire repository, use -w deliberately. • If you cannot explain the owner, do not install it yet.
Problem - multiple pnpm-lock.yaml files Symptom: a lockfile appears inside an application in addition to the workspace root. That often means a package was created or installed outside workspace awareness, or commands were run before the workspace root existed.
Diagnosis: inspect the repository tree and determine which lockfile belongs to the actual workspace. Avoid deleting lockfiles blindly; understand how they were created first.
Problem - Node changed after reopening PowerShell Check:
node --version
Get-Command node
Get-Content .\.node-versionIf fnm automatic switching is configured, entering the repository should align Node with .node-version. If it does not, debug the fnm shell initialization from Phase 01 rather than changing the repository version pin.
Problem - workspace package does not appear Check whether the folder actually contains a package.json and whether its path matches the pnpm-workspace.yaml glob. A folder name matching apps/* is not enough by itself.
Problem - endless line-ending changes Symptom: Git shows files changed even though their text appears identical. Inspect .gitattributes and local Git line-ending settings. Repository attributes should provide a predictable project-level policy. Avoid solving line-ending noise by disabling normalization randomly per developer.
Problem - .env is still tracked after adding it to .gitignore Git ignore rules do not stop tracking a file that is already in the index. If the file contained a real credential, rotate the credential. Then remove it from version control history/index using an appropriate remediation workflow. Do not assume adding .env to .gitignore makes an exposed secret safe.
Problem - nested .git directory If git status inside a subfolder appears to show a completely different repository, someone may have run git init inside the monorepo. Inspect hidden files with:
A normal TaskFlow course repository should have one .git directory at the root. Remove a nested repository only after confirming it is accidental and that no unique history is needed.
where/version json/yaml git/lockfile
evidence evidence evidence
A professional pre-commit rhythm
git status
git diff
# edit or verify
git add .
git diff --staged
# only then
git commit -m "..."This rhythm is intentionally repetitive. It makes accidental secrets, generated output and unrelated changes visible before they become history.
Phase 02 operational checklist • I can identify the workspace root without guessing. • I know which package should own a dependency before installing it. • I inspect staged changes before committing. • I can distinguish a pnpm warning from a Git problem or Node-version problem. • I prefer one small evidence-based correction over deleting node_modules or reinstalling everything.
CI turns repository rules into automated gates. A useful pipeline must be understandable, reproducible locally, secure, and able to fail for the right reasons.
Restate the goal of “Professional Monorepo Workflow and Troubleshooting” as one observable behavior. Write the success signal before touching code.
Trace the boundary map: git event → runner → install → quality gates → artifact/deploy decision. Mark the one boundary this lesson changes.
Inspect the current repository state and record the exact files, route, table, or runtime involved. Avoid creating an abstraction before you can name the existing owner.
Implement the smallest vertical slice. Add one coherent change, run the narrowest verification command, and read the output before continuing.
Connect the slice to TaskFlow’s phase artifact: TaskFlow repository root with apps/web, apps/api, shared packages, workspace metadata, root scripts, and clean Git hygiene.. Verify behavior from the outside as a user or API client would.
Create one controlled failure that is safe to reproduce. Predict the symptom first, capture evidence, locate the earliest broken boundary, then fix only that cause.
Close the reference and rebuild or explain the core change from memory. Record what you would monitor or test before trusting the same change in production.
name: CI
on: [pull_request]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm lint && pnpm typecheck && pnpm test && pnpm buildDo not copy this as a finished answer. Predict what each boundary does, type the smallest useful slice, run it, then compare the result with your prediction.
Compare Node/pnpm versions, lockfile state, environment variables, OS assumptions, and generated artifacts.
Set least-privilege permissions at workflow/job level and isolate untrusted pull-request code from secrets.
Without copying the final source, create a second small scenario that applies “Professional Monorepo Workflow and Troubleshooting” to a different TaskFlow resource or input. Write the acceptance criteria first, implement it, and provide the evidence that each criterion is satisfied.
Inspect pnpm why/list output so you can explain where a dependency is owned and why.
Use the smallest change that demonstrates this lesson. Stop after it works and capture evidence.Duplicating tsconfig settings in every package
Predict the symptom before causing the failure. Then locate the earliest boundary where reality diverges from expectation.Why does this responsibility live here, what input does it trust, what output proves success, and what would go wrong if another layer owned it?
If your explanation is vague, repeat the boundary trace before moving on.Close the reference. Reproduce the core idea from memory or explain the exact request/data flow aloud. Then check your diff or notes for accidental shortcuts that bypass validation, authorization, error handling, or verification earned in earlier phases.