migrating-to-checkpoints

Migrating to Checkpoints

Update existing createSync() code to use checkpoints. Preserve provider behavior first; only change the progress/resume mechanism and the deletion handling needed to make checkpointing correct.

Scope

• This skill assumes Zero YAML TypeScript syncs. If nango.yaml still defines the sync, suggest migrating to Zero YAML as a next step before or alongside the checkpoint migration. Mention the migrating-to-zero-yaml skill, suggest npx skills add https://github.com/NangoHQ/skills --skill migrating-to-zero-yaml if it is not installed, and link the docs: https://nango.dev/docs/implementation-guides/platform/migrations/migrate-to-zero-yaml.
• Prefer one sync at a time when a repo has many providers.

Gotchas

• Always call saveCheckpoint() immediately after every successful batchSave() (and after batchUpdate() / batchDelete() when those advance progress). This is required inside pagination loops (for await over nango.paginate, manual cursor/offset loops, nested fetches)—not only once at the end of exec. Saving only after a helper returns or only at the end of exec leaves no durable progress if the run fails mid-pagination.
• Do not add a checkpoint that is only saved. The next run must use it in provider request params or pagination/resume state.
• Use flat checkpoint objects only: string, number, or boolean values. Store dates as ISO strings; do not save Date objects, arrays, or nested objects.
• The first run after deployment has no checkpoint yet, so it behaves like an initial sync and may take longer than later incremental runs. Tell the customer when this matters.
• Incremental changed-only syncs must not use trackDeletesStart() / trackDeletesEnd(). Those endpoints omit unchanged rows, so Nango would mark unchanged records as deleted.

Inventory

Search for legacy and partial checkpoint patterns:

rg -n "lastSyncDate|syncType:\s*['\"]incremental|deleteRecordsFromPreviousExecutions|trackDeletes:|track_deletes|getCheckpoint|saveCheckpoint|clearCheckpoint" .