Use when building the Nango monorepo or verifying TypeScript compilation - covers build commands, project references, common tsc errors, and package dependency order
Nango is a TypeScript monorepo using npm workspaces and TypeScript project references (no Turborepo/Nx). Build order matters — packages depend on each other via tsconfig.build.json references.
| Command | Purpose | When to use |
|---|---|---|
npm run ts-build | Full TypeScript build with project refs | After cross-package changes |
npx tsc -p packages/server/tsconfig.build.json --noEmit | Type-check single package | Quick check during development |
npm run ts-clean && npm run ts-build | Clean rebuild | When incremental build gives stale errors |
npm install | Install deps + link workspaces |
| After changing dependencies or in fresh worktree |
All commands run from the repo root.
Build order follows tsconfig.build.json references:
types, utils, frontend — no internal depsdatabase, kvstore, logs, keystoreshared, node-client, nango-yaml, runner, scheduler, orchestratorserver, webapp, connect-ui, cliKey rule: @nangohq/types is declaration-only (emitDeclarationOnly: true). It cannot export runtime values — only TypeScript types. Runtime consts go in @nangohq/utils.
Always run npm install before building — after pulling new changes, switching branches, or in a fresh worktree/checkout. Missing or outdated node_modules causes Cannot find module errors that look like code issues but are just missing deps.
# Standard build flow
npm install
npm run ts-build
# After editing types used across packages — full build
npm run ts-build
# After editing only server code — single package check
npx tsc -p packages/server/tsconfig.build.json --noEmit
# After editing shared + server — build the dependency chain
npx tsc -p packages/shared/tsconfig.build.json && npx tsc -p packages/server/tsconfig.build.json --noEmit
Fresh worktrees need dependencies installed:
npm install
Without this, npx tsc and other tools won't be available.
| Error | Cause | Fix |
|---|---|---|
Cannot find module 'X' or its corresponding type declarations | Dependencies not installed or outdated | Run npm install first |
Failed to resolve entry for package '@nangohq/types' | Trying to import runtime value from types package | Move the value to @nangohq/utils — types is declaration-only |
Cannot find module '@nangohq/shared' in build | Dependency not built yet | Run npm run ts-build (full build) or build dependency first |
Stale .tsbuildinfo giving phantom errors | Incremental build cache is wrong | npm run ts-clean && npm run ts-build |
Type 'X' is not assignable to type 'Y' across packages | Types package changed but dependents not rebuilt | Full rebuild: npm run ts-build |
Missing dist/ directory | Package never built or cleaned | npm run ts-build |
When adding API endpoint types:
packages/types/lib/ (appropriate subdirectory)packages/types/lib/index.tsAPIEndpoints union in packages/types/lib/api.endpoints.tsnpm run ts-build to verify