SKILL.md
Building and Verifying Nango
Overview
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.
Quick Reference
| 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.
Package Dependency Layers
Build order follows tsconfig.build.json references:
- Core:
types,utils,frontend— no internal deps - Infrastructure:
database,kvstore,logs,keystore - Services:
shared,node-client,nango-yaml,runner,scheduler,orchestrator - Applications:
server,webapp,connect-ui,cli
Key rule: @nangohq/types is declaration-only (emitDeclarationOnly: true). It cannot export runtime values — only TypeScript types. Runtime consts go in @nangohq/utils.
Build Workflow
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-buildVerifying Changes
# 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 --noEmitNew Worktree Setup
Fresh worktrees need dependencies installed:
npm installWithout this, npx tsc and other tools won't be available.
Common Errors
| 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 |
Adding New Endpoint Types
When adding API endpoint types:
- Define the type in
packages/types/lib/(appropriate subdirectory) - Export from
packages/types/lib/index.ts - Add to
APIEndpointsunion inpackages/types/lib/api.endpoints.ts - Run
npm run ts-buildto verify