Terminal
Terminal/Skill
Design rules for writing Nango actions and syncs covering schemas, checkpoints, deletes and retries, before choosing a local or remote workflow.
By Nango
Works with
npx skills add nangohq/skills --skill building-nango-functionsBuild 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.
createAction()createSync()If the task is a sync, read references/syncs.md before writing code and state one of these paths first:
updated_at, modified_since, changed-records endpoint, cursor, page token, offset/page, since_id, or webhook)Invalid sync implementations:
saveCheckpoint() without getCheckpoint()syncType: 'incremental' or nango.lastSyncDate in a new synccheckpoint schema, or one that is never saved after each page — the run restarts from page 1 whenever it exceeds the execution windowsaveCheckpoint() guarded so it only runs when more pages remain (e.g. if (nextCursor) { await nango.saveCheckpoint(...) }). Every successful page, including the last, must call saveCheckpoint(); otherwise a one-page sync reaches clearCheckpoint() with no checkpoint row and fails with checkpoint_conflict.trackDeletesEnd() before clearCheckpoint(), or without a preceding clearCheckpoint() at alltrackDeletesStart() / trackDeletesEnd() with a changed-only checkpoint (modified_after, updated_after, changed-records endpoint). Those requests omit unchanged rows, so trackDeletesEnd() will falsely delete them.trackDeletesStart() / trackDeletesEnd() in an incremental sync that already has explicit deleted-record eventsAction:
createAction()references/actions.md before writing codeSync:
createSync()references/syncs.md before writing codeAlways:
Action-specific:
{} for no-input actions)Sync-specific:
since_id, or composite)If any required external values are missing, ask a targeted question after checking the repo and provider docs. For syncs, choose a checkpoint plus deletion strategy whenever the provider supports one. If you cannot find a viable checkpoint strategy, state exactly why before writing a full refresh.
createAction() / createSync().zod, crypto/node:crypto, and url/node:url.fs, no axios, 2 MB output limit). Use a proxy script in {integration}/proxy/ with @nangohq/node instead — see references/actions.md.0; set retries deliberately. Treat 3 as the normal maximum; for sync provider calls, values above 3 are effectively forbidden unless docs prove they are safe and necessary. Avoid retries for non-idempotent writes unless the API supports idempotency.endpoint and sync endpoints. Trigger actions by action name through the SDK/API, and consume sync records through the records API.id.checkpoint schema, call nango.getCheckpoint() first, and nango.saveCheckpoint() after each page or batch.since, updated_after, cursor, page_token, offset, page, since_id, etc.). Saving one without using it is not incremental sync.syncType: 'incremental' or nango.lastSyncDate.nango.paginate(...) + nango.batchSave(...). Avoid manual while (true) loops when cursor, link, or offset pagination fits.batchDelete() when the provider returns deletions, tombstones, or delete webhooks.checkpoint schema (page/cursor/offset) covering pagination progress, not just incremental syncs. Nango syncs run inside a time-limited execution window; a full refresh with no checkpoint restarts from page 1 on every run that exceeds the window, wasting compute re-fetching the same early pages and never reaching the rest.deleteRecordsFromPreviousExecutions() is deprecated. For full refresh, call trackDeletesStart() on every execution (safe/idempotent — it will not overwrite the start of an already-open window), then saveCheckpoint() after each page, clearCheckpoint() after the last page, and trackDeletesEnd() only after that clearCheckpoint().saveCheckpoint() after every successful page, including the last, before calling clearCheckpoint(). Never guard the save with "more pages remain." If a distinct execution path creates no checkpoint at all (for example, it processes no pages), do not call clearCheckpoint() on that path; it throws checkpoint_conflict at runtime. This exception is not a substitute for saving the terminal page.trackDeletesStart() / trackDeletesEnd() with changed-only checkpoints (modified_after, updated_after, changed-records endpoints, etc.). They omit unchanged rows, so trackDeletesEnd() would delete them.trackDeletesEnd() only in the run that finishes and clears the checkpoint.team_id, workspace_id, guild_id), set autoStart: false. The sync cannot run until the caller has set the metadata, so starting it automatically would fail..describe() examples for IDs, timestamps, enums, and URLs.any; use inline mapping types.cursor plus a next-cursor field in the majority casing of that API (next_cursor, nextCursor, etc.).nango.zodValidateInput() only when you need custom validation or logging; otherwise rely on schemas plus the chosen validation workflow..optional()..nullable() only when null has meaning, usually clear-on-update; add .optional() when callers may omit the field too..optional() for omitted fields, .nullable() for explicit null, .nullish() only when the provider truly does both..optional() and normalize upstream null to omission unless null matters..optional() for non-required inputs and normalized outputs; widen only when the upstream contract justifies it..nullable() over z.union([z.null(), T]) or z.union([T, z.null()]).null only when the output schema allows it.z.object() strips unknown keys by default. For provider pass-through use z.object({}).passthrough(), z.record(z.unknown()), or z.unknown() with minimal refinements.user_id, userId), names (channel_name, channelName), emails (user_email, userEmail), URLs (callback_url, callbackUrl), and timestamps (created_at, createdAt).Mapping example (API expects a different parameter name):
const InputSchema = z.object({
userId: z.string()
});
const config: ProxyConfiguration = {
endpoint: 'users.info',
params: {
user: input.userId
},
retries: 3
};
If the API is snake_case, use user_id instead. The goal is API consistency.
references/actions.mdreferences/syncs.md--save, Vitest): https://nango.dev/docs/implementation-guides/platform/functions/testingIf web fetching returns incomplete docs (JS-rendered):