building-nango-functions

Build Nango Functions

Build Nango action and sync implementations without choosing the execution workflow.

This skill covers the function design contract: schemas, provider calls, action outputs, sync models, checkpoints, deletion handling, metadata, retries, and runtime constraints. It intentionally does not cover local CLI validation/deploy or remote API compile/dryrun/deploy.

If the task becomes clearly local/CLI-based, use building-nango-functions-locally instead. If it becomes clearly remote/API-based, use building-nango-functions-remotely instead.

Implementation Scope

• Build or modify a Nango function implementation
• Build an action in Nango with createAction()
• Build a sync in Nango with createSync()
• Use the active workflow skill for compile, dryrun, test, and deploy mechanics

Sync Strategy Gate (required before writing code)

If the task is a sync, read references/syncs.md before writing code and state one of these paths first:

• Checkpoint plan:
  • change source (updated_at, modified_since, changed-records endpoint, cursor, page token, offset/page, since_id, or webhook)
  • checkpoint schema
  • how the checkpoint changes the provider request or resume state
  • whether the request still walks the full dataset or returns changed rows only
  • delete strategy
• Full refresh blocker:
  • exact provider limitation from the docs or sample payloads
  • why checkpoints cannot work here

Invalid sync implementations:

• full refresh because it is simpler
• saveCheckpoint() without getCheckpoint()
• reading or saving a checkpoint without using it in request params or pagination state
• using syncType: 'incremental' or nango.lastSyncDate in a new sync
• using trackDeletesStart() / trackDeletesEnd() with a changed-only checkpoint (modified_after, updated_after, changed-records endpoint). Those requests omit unchanged rows, so trackDeletesEnd() will falsely delete them.
• using trackDeletesStart() / trackDeletesEnd() in an incremental sync that already has explicit deleted-record events