building-nango-functions-locally

Build Nango Functions Locally

Build deployable Nango actions and syncs in a checked-out Nango project with the local CLI validation and test workflow.

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

Choose the Path

Action:

• One-time request, user-triggered, built with createAction()
• Read references/actions.md before writing code

Sync:

• Scheduled or webhook-driven cache updates built with createSync()
• Complete the Sync Strategy Gate first
• Read references/syncs.md before writing code

Required Inputs (Ask User if Missing)