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
- a full refresh with no
checkpoint schema, or one that is never saved after each page — the run restarts from page 1 whenever it exceeds the execution window
saveCheckpoint() 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.
- calling
trackDeletesEnd() before clearCheckpoint(), or without a preceding clearCheckpoint() at all
- 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)
Always:
- Integration ID (provider name)
- Script/function name (kebab-case)
- API reference URL or sample response
- Connection ID if the active workflow will validate or dryrun the function
Action-specific:
- Use case summary
- Input parameters
- Output fields
- Metadata JSON if required
- Test input JSON if the active workflow will validate or dryrun the action (use
{} for no-input actions)
Sync-specific:
- Model name (singular, PascalCase)
- Frequency (every hour, every 5 minutes, etc.)
- Checkpoint schema (timestamp, cursor, page token, offset/page,
since_id, or composite)
- How the checkpoint changes the provider request or resume state
- Delete strategy (deleted-record endpoint/webhook, or why full refresh is required)
- If proposing a full refresh, the exact provider limitation that blocks checkpoints from the docs/sample response
- Metadata JSON if required (team_id, workspace_id)
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.
Non-Negotiable Rules
Shared platform constraints
- Nango functions use
createAction() / createSync().
- You cannot add arbitrary packages. Use relative imports only when the chosen workflow supports them; built-ins include
zod, crypto/node:crypto, and url/node:url.
- Use the Nango HTTP API for connection lookup, credentials, and proxy calls outside function code. Do not invent CLI token or connection commands.
- Add an API doc link comment above each provider call.
- Action outputs cannot exceed 2MB.
- File uploads and downloads cannot be implemented as actions (sandboxed runtime: no
fs, no axios, 2 MB output limit). Use a proxy script in {integration}/proxy/ with @nangohq/node instead — see references/actions.md.
- HTTP retries default to
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.
- Do not set deprecated function definition routing fields: action
endpoint and sync endpoints. Trigger actions by action name through the SDK/API, and consume sync records through the records API.
Sync rules
- Sync records need a stable string
id.
- New syncs should define a
checkpoint schema, call nango.getCheckpoint() first, and nango.saveCheckpoint() after each page or batch.
- A checkpoint is valid only if it changes the request or resume state (
since, updated_after, cursor, page_token, offset, page, since_id, etc.). Saving one without using it is not incremental sync.
- New syncs must not use
syncType: 'incremental' or nango.lastSyncDate.
- Default to
nango.paginate(...) + nango.batchSave(...). Avoid manual while (true) loops when cursor, link, or offset pagination fits.
- Prefer
batchDelete() when the provider returns deletions, tombstones, or delete webhooks.
- Use full refresh only if the provider cannot return changes, deletions, or resume state, or if the dataset is tiny.
- For full refresh, cite the exact provider limitation from docs or payloads. "It is easier" is not enough.
- Full refresh syncs still need a
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().
- In a full refresh, call
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.
- Never combine
trackDeletesStart() / trackDeletesEnd() with changed-only checkpoints (modified_after, updated_after, changed-records endpoints, etc.). They omit unchanged rows, so trackDeletesEnd() would delete them.
- Checkpointed full refreshes are still full refreshes. Call
trackDeletesEnd() only in the run that finishes and clears the checkpoint.
- If a sync requires metadata (e.g.
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.
Conventions
- Match field casing to the external API. Passthrough fields keep provider casing; non-passthrough fields should use the majority casing of that API.
- Prefer explicit field names.
- Add
.describe() examples for IDs, timestamps, enums, and URLs.
- Avoid
any; use inline mapping types.
- List actions should expose
cursor plus a next-cursor field in the majority casing of that API (next_cursor, nextCursor, etc.).
- Use
nango.zodValidateInput() only when you need custom validation or logging; otherwise rely on schemas plus the chosen validation workflow.
Schema Semantics
- Default non-required inputs to
.optional().
- Use
.nullable() only when null has meaning, usually clear-on-update; add .optional() when callers may omit the field too.
- Raw provider schemas should match the provider:
.optional() for omitted fields, .nullable() for explicit null, .nullish() only when the provider truly does both.
- Final action outputs and normalized sync models should prefer
.optional() and normalize upstream null to omission unless null matters.
- Default generated schemas to
.optional() for non-required inputs and normalized outputs; widen only when the upstream contract justifies it.
- Prefer
.nullable() over z.union([z.null(), T]) or z.union([T, z.null()]).
- Return
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.
Field Naming and Casing Rules
- Use explicit suffixes in the API's majority casing: IDs (
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
- Action patterns, CRUD examples, metadata usage, and ActionError examples:
references/actions.md
- Sync patterns, concrete checkpoint examples, delete strategies, and full refresh fallback:
references/syncs.md
Useful Nango docs (quick links)
When API Docs Do Not Render
If web fetching returns incomplete docs (JS-rendered):
- Ask the user for a sample response
- Use existing Nango actions or syncs in the workspace as a pattern when they exist
- Use the skill-specific validation or dryrun workflow until it passes
1---
2name: building-nango-functions
3description: Builds Nango Function implementation patterns for createAction() and createSync() without choosing a local CLI or remote API workflow. Use only when the user asks to create or update a Nango action or sync and it is unclear whether the work should happen in a checked-out project via CLI or through Nango remote APIs. Do not load when building-nango-functions-locally or building-nango-functions-remotely applies; those skills overlap with this content and add workflow-specific validation and deploy details.
4metadata:
5 source: https://skillmd.com/skills/nangohq/building-nango-functions
6---
7
8# Build Nango Functions
9Build Nango action and sync implementations without choosing the execution workflow.
10
11This 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.
12
13If 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.
14
15## Implementation Scope
16- Build or modify a Nango function implementation
17- Build an action in Nango with `createAction()`
18- Build a sync in Nango with `createSync()`
19- Use the active workflow skill for compile, dryrun, test, and deploy mechanics
20
21## Sync Strategy Gate (required before writing code)
22
23If the task is a sync, read `references/syncs.md` before writing code and state one of these paths first:
24
25- Checkpoint plan:
26 - change source (`updated_at`, `modified_since`, changed-records endpoint, cursor, page token, offset/page, `since_id`, or webhook)
27 - checkpoint schema
28 - how the checkpoint changes the provider request or resume state
29 - whether the request still walks the full dataset or returns changed rows only
30 - delete strategy
31- Full refresh blocker:
32 - exact provider limitation from the docs or sample payloads
33 - why checkpoints cannot work here
34
35Invalid sync implementations:
36- full refresh because it is simpler
37- `saveCheckpoint()` without `getCheckpoint()`
38- reading or saving a checkpoint without using it in request params or pagination state
39- using `syncType: 'incremental'` or `nango.lastSyncDate` in a new sync
40- a full refresh with no `checkpoint` schema, or one that is never saved after each page — the run restarts from page 1 whenever it exceeds the execution window
41- `saveCheckpoint()` 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`.
42- calling `trackDeletesEnd()` before `clearCheckpoint()`, or without a preceding `clearCheckpoint()` at all
43- 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.
44- using `trackDeletesStart()` / `trackDeletesEnd()` in an incremental sync that already has explicit deleted-record events
45
46## Choose the Path
47
48Action:
49- One-time request, user-triggered, built with `createAction()`
50- Read `references/actions.md` before writing code
51
52Sync:
53- Scheduled or webhook-driven cache updates built with `createSync()`
54- Complete the Sync Strategy Gate first
55- Read `references/syncs.md` before writing code
56
57## Required Inputs (Ask User if Missing)
58
59Always:
60- Integration ID (provider name)
61- Script/function name (kebab-case)
62- API reference URL or sample response
63- Connection ID if the active workflow will validate or dryrun the function
64
65Action-specific:
66- Use case summary
67- Input parameters
68- Output fields
69- Metadata JSON if required
70- Test input JSON if the active workflow will validate or dryrun the action (use `{}` for no-input actions)
71
72Sync-specific:
73- Model name (singular, PascalCase)
74- Frequency (every hour, every 5 minutes, etc.)
75- Checkpoint schema (timestamp, cursor, page token, offset/page, `since_id`, or composite)
76- How the checkpoint changes the provider request or resume state
77- Delete strategy (deleted-record endpoint/webhook, or why full refresh is required)
78- If proposing a full refresh, the exact provider limitation that blocks checkpoints from the docs/sample response
79- Metadata JSON if required (team_id, workspace_id)
80
81If 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.
82
83## Non-Negotiable Rules
84
85### Shared platform constraints
86
87- Nango functions use `createAction()` / `createSync()`.
88- You cannot add arbitrary packages. Use relative imports only when the chosen workflow supports them; built-ins include `zod`, `crypto`/`node:crypto`, and `url`/`node:url`.
89- Use the Nango HTTP API for connection lookup, credentials, and proxy calls outside function code. Do not invent CLI token or connection commands.
90- Add an API doc link comment above each provider call.
91- Action outputs cannot exceed 2MB.
92- File uploads and downloads cannot be implemented as actions (sandboxed runtime: no `fs`, no `axios`, 2 MB output limit). Use a proxy script in `{integration}/proxy/` with `@nangohq/node` instead — see `references/actions.md`.
93- HTTP retries default to `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.
94- Do not set deprecated function definition routing fields: action `endpoint` and sync `endpoints`. Trigger actions by action name through the SDK/API, and consume sync records through the records API.
95
96### Sync rules
97
98- Sync records need a stable string `id`.
99- New syncs should define a `checkpoint` schema, call `nango.getCheckpoint()` first, and `nango.saveCheckpoint()` after each page or batch.
100- A checkpoint is valid only if it changes the request or resume state (`since`, `updated_after`, `cursor`, `page_token`, `offset`, `page`, `since_id`, etc.). Saving one without using it is not incremental sync.
101- New syncs must not use `syncType: 'incremental'` or `nango.lastSyncDate`.
102- Default to `nango.paginate(...)` + `nango.batchSave(...)`. Avoid manual `while (true)` loops when `cursor`, `link`, or `offset` pagination fits.
103- Prefer `batchDelete()` when the provider returns deletions, tombstones, or delete webhooks.
104- Use full refresh only if the provider cannot return changes, deletions, or resume state, or if the dataset is tiny.
105- For full refresh, cite the exact provider limitation from docs or payloads. "It is easier" is not enough.
106- Full refresh syncs still need a `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.
107- `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()`.
108- In a full refresh, call `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.
109- Never combine `trackDeletesStart()` / `trackDeletesEnd()` with changed-only checkpoints (`modified_after`, `updated_after`, changed-records endpoints, etc.). They omit unchanged rows, so `trackDeletesEnd()` would delete them.
110- Checkpointed full refreshes are still full refreshes. Call `trackDeletesEnd()` only in the run that finishes and clears the checkpoint.
111- If a sync requires metadata (e.g. `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.
112
113### Conventions
114
115- Match field casing to the external API. Passthrough fields keep provider casing; non-passthrough fields should use the majority casing of that API.
116- Prefer explicit field names.
117- Add `.describe()` examples for IDs, timestamps, enums, and URLs.
118- Avoid `any`; use inline mapping types.
119- List actions should expose `cursor` plus a next-cursor field in the majority casing of that API (`next_cursor`, `nextCursor`, etc.).
120- Use `nango.zodValidateInput()` only when you need custom validation or logging; otherwise rely on schemas plus the chosen validation workflow.
121
122### Schema Semantics
123
124- Default non-required inputs to `.optional()`.
125- Use `.nullable()` only when `null` has meaning, usually clear-on-update; add `.optional()` when callers may omit the field too.
126- Raw provider schemas should match the provider: `.optional()` for omitted fields, `.nullable()` for explicit `null`, `.nullish()` only when the provider truly does both.
127- Final action outputs and normalized sync models should prefer `.optional()` and normalize upstream `null` to omission unless `null` matters.
128- Default generated schemas to `.optional()` for non-required inputs and normalized outputs; widen only when the upstream contract justifies it.
129- Prefer `.nullable()` over `z.union([z.null(), T])` or `z.union([T, z.null()])`.
130- Return `null` only when the output schema allows it.
131- `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.
132
133### Field Naming and Casing Rules
134
135- Use explicit suffixes in the API's majority casing: IDs (`user_id`, `userId`), names (`channel_name`, `channelName`), emails (`user_email`, `userEmail`), URLs (`callback_url`, `callbackUrl`), and timestamps (`created_at`, `createdAt`).
136
137Mapping example (API expects a different parameter name):
138
139```typescript
140const InputSchema = z.object({
141 userId: z.string()
142});
143
144const config: ProxyConfiguration = {
145 endpoint: 'users.info',
146 params: {
147 user: input.userId
148 },
149 retries: 3
150};
151```
152
153If the API is snake_case, use `user_id` instead. The goal is API consistency.
154
155## References
156
157- Action patterns, CRUD examples, metadata usage, and ActionError examples: `references/actions.md`
158- Sync patterns, concrete checkpoint examples, delete strategies, and full refresh fallback: `references/syncs.md`
159
160## Useful Nango docs (quick links)
161- Functions runtime SDK reference: https://nango.dev/docs/reference/functions
162- Implement an action: https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
163- Implement a sync: https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
164- Checkpoints: https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
165- Deletion detection (full vs incremental): https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
166- Testing integrations (dryrun, `--save`, Vitest): https://nango.dev/docs/implementation-guides/platform/functions/testing
167- Nango HTTP API reference: https://nango.dev/docs/reference/api
168
169## When API Docs Do Not Render
170
171If web fetching returns incomplete docs (JS-rendered):
172- Ask the user for a sample response
173- Use existing Nango actions or syncs in the workspace as a pattern when they exist
174- Use the skill-specific validation or dryrun workflow until it passes