Index of every page on this site: llms.txt
All skills
nangohq avatar

/building-and-verifying

@0c949ea
by Nangonangohq/nango13k stars
1,543
Run it yourself

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

Use this Skill: https://skilld.dev/gh/nangohq/nango/building-and-verifying

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈47 tokens for metadata: the name and description. ≈898 when used: this file.

Description uses 2.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈190 characters, or 2.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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
npm ci Install deps from the lockfile, never rewriting it In a fresh worktree or checkout

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 install dependencies before building — npm install after pulling new changes or switching branches, npm ci 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. Use npm ci: npm install into an empty node_modules rewrites package-lock.json.

npm ci

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    The skill provides instructions for building and verifying a TypeScript monorepo. It uses standard development tools and commands consistent with its stated purpose.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at 0c949ea. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 weeks ago

README badge

README badge for nangohq/nango/building-and-verifying