building-and-verifying

name	building-and-verifying
description	Use when building the Nango monorepo or verifying TypeScript compilation - covers build commands, project references, common tsc errors, and package dependency order

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:

1. Core: types, utils, frontend — no internal deps
2. Infrastructure: database, kvstore, logs, keystore
3. Services: shared, node-client, nango-yaml, runner, scheduler, orchestrator
4. 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-build

Verifying 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 --noEmit

New Worktree Setup

Fresh worktrees need dependencies installed:

npm install

Without 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:

1. Define the type in packages/types/lib/ (appropriate subdirectory)
2. Export from packages/types/lib/index.ts
3. Add to APIEndpoints union in packages/types/lib/api.endpoints.ts
4. Run npm run ts-build to verify