building-nango-functions-locally
Skill2 starsChanged 5 months agoApache-2.0View on GitHub
Builds Nango Functions in a checked-out Zero YAML TypeScript Nango project using local files, index.ts registration, nango dryrun, generated tests, and optional nango deploy via CLI. Use when creating, updating, validating, testing, or deploying Nango actions or syncs locally in a repo. This content overlaps with building-nango-functions but adds CLI workflow details, so load this instead of building-nango-functions whenever a local project, local files, Nango root, CLI, dryrun, generated tests, or nango deploy workflow is indicated.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- NangoHQ/skillsedited, first seen Nov 4, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- NangoHQ/skills★ 372% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository168 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/CO-STAR-UI-CREATOR/AGENT.mdcCursor rule
- .cursor/rules/CO-STAR-UI-CREATOR/CO-STAR-CREATOR.mdCursor rule
- .cursor/rules/CO-STAR-UI-CREATOR/CO-STAR-PROMPT.mdCursor rule
- .cursor/rules/CO-STAR-UI-CREATOR/README.mdCursor rule
- .cursor/rules/CO-STAR-UI-CREATOR/ui.mdCursor rule
- 401-403-bypass-techniquesSkill
- active-directory-acl-abuseSkill
- active-directory-certificate-servicesSkill
- active-directory-kerberos-attacksSkill
- agent-browserSkill
- ai-ml-securitySkill
- ai-seoSkill
- android-pentesting-tricksSkill
- anti-debugging-techniquesSkill
- api-auth-and-jwt-abuseSkill
- api-authorization-and-bolaSkill
- api-recon-and-docsSkill
- api-secSkill
- arbitrary-write-to-rceSkill
- arize-adminSkill
- arize-ai-provider-integrationSkill
- arize-annotationSkill
- arize-compliance-auditSkill
- arize-datasetSkill
- arize-evaluatorSkill
- arize-experimentSkill
- arize-instrumentationSkill
- arize-linkSkill
- arize-prompt-optimizationSkill
- arize-promptsSkill
- arize-traceSkill
- authbypass-authentication-flawsSkill
- auth-secSkill
- binary-protection-bypassSkill
- browser-exploitation-v8Skill
- building-nango-functions-remotelySkill
- building-nango-functionsSkill
- business-logic-vulnerabilitiesSkill
- business-logic-vulnSkill
- classical-cipher-analysisSkill
- clickjackingSkill
- cmdi-command-injectionSkill
- code-obfuscation-deobfuscationSkill
- compliance-checkSkill
- compliance-trackingSkill
- container-escape-techniquesSkill
- core-engineeringSkill
- cors-cross-origin-misconfigurationSkill
- crlf-injectionSkill
- csp-bypass-advancedSkill
- csrf-cross-site-request-forgerySkill
- csv-formula-injectionSkill
- d3-visualizationSkill
- dangling-markup-injectionSkill
- defi-attack-patternsSkill
- dependency-confusionSkill
- deserialization-insecureSkill
- dns-rebinding-attacksSkill
- documentation-writerSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
49 rules. About 0 are common, 17 are distinctive, and 32 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
32
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Use the active workflow skill for compile, dryrun, test, and deploy mechanics
- Very specific: line 17
If the task is a sync, read references/syncs.md before writing code and state one of these paths first:
- Very specific: line 41
Read references/actions.md before writing code
- Very specific: line 61
Test input JSON if the active workflow will validate or dryrun the action (use {} for no-input actions)
- Distinctive: line 68
Delete strategy (deleted-record endpoint/webhook, or why full refresh is required)
- Distinctive: line 69
If proposing a full refresh, the exact provider limitation that blocks checkpoints from the docs/sample response
- Distinctive: line 80
Use the Nango HTTP API for connection lookup, credentials, and proxy calls outside function code.
- Distinctive: line 81
Add an API doc link comment above each provider call.
- Very specific: line 85
Do not set deprecated function definition routing fields: action endpoint and sync endpoints.
- Very specific: line 93
Default to nango.paginate(...) + nango.batchSave(...).
- Very specific: line 94
Prefer batchDelete() when the provider returns deletions, tombstones, or delete webhooks.
- Distinctive: line 95
Use full refresh only if the provider cannot return changes, deletions, or resume state, or if the dataset is tiny.
- Very specific: line 98
Never combine trackDeletesStart() / trackDeletesEnd() with changed-only checkpoints (modified_after, updated_after, changed-records …
- Very specific: line 100
If a sync requires metadata (e.g.
- Distinctive: line 105
Prefer explicit field names.
- Very specific: line 106
Add .describe() examples for IDs, timestamps, enums, and URLs.
- Very specific: line 107
Avoid any; use inline mapping types.
- Very specific: line 109
Use nango.zodValidateInput() only when you need custom validation or logging.
- Very specific: line 113
Default non-required inputs to .optional().
- Very specific: line 114
Use .nullable() only when null has meaning, usually clear-on-update.
- Very specific: line 117
Default generated schemas to .optional() for non-required inputs and normalized outputs.
- Very specific: line 118
Prefer .nullable() over z.union([z.null(), T]) or z.union([T, z.null()]).
- Very specific: line 124
Use explicit suffixes in the API's majority casing: IDs (user_id, userId), names (channel_name, channelName), emails (user_email, …
- Very specific: line 142
If the API is snake_case, use user_id instead.
- Distinctive: line 160
If web fetching returns incomplete docs (JS-rendered):
- Distinctive: line 161
Ask the user for a sample response
- Distinctive: line 162
Use existing Nango actions or syncs in the workspace as a pattern when they exist
- Distinctive: line 163
Use the skill-specific validation or dryrun workflow until it passes
- Very specific: line 167
Read the matching reference file: references/actions.md or references/syncs.md.
- Very specific: line 171
Create or update the function under {integrationId}/actions/ or {integrationId}/syncs/, apply the shared schema and casing rules, then …
- Distinctive: line 173
If validation cannot pass, stop and report the missing external state or inputs.
- Very specific: line 174
After validation passes, run nango dryrun ...
- Very specific: line 187
If you see YAML PROJECT DETECTED:
- Distinctive: line 190
Do not attempt to mix YAML and TypeScript.
- Distinctive: line 196
Do not create files until you confirm the Nango root:
- Distinctive: line 205
Do not use absolute paths as a workaround
- Distinctive: line 207
All file paths must be relative to the Nango root.
- Very specific: line 229
All actions and syncs must be imported in index.ts
- Very specific: line 233
Use side-effect imports only.
- Very specific: line 246
Run nango dryrun ... --validate -e dev --no-interactive --auto-confirm until it passes.
- Distinctive: line 249
If validation cannot pass, stop and state the missing external state or inputs required.
- Very specific: line 250
After validation passes, run nango dryrun ...
- Very specific: line 251
Run nango generate:tests, then npm test.
- Very specific: line 279
Treat <script-name>.test.json as generated output.
- Very specific: line 280
If mocks are wrong or stale, fix the code and re-record with --save.
- Very specific: line 281
Do not hard-code error payloads in *.test.json.
- Very specific: line 283
Use --integration-id <integration-id> when script names overlap across integrations.
- Very specific: line 284
Prefer --checkpoint for new incremental syncs.
- Very specific: line 285
If nango is not on PATH, use npx nango ....
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- change source (
- 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()withoutgetCheckpoint()- reading or saving a checkpoint without using it in request params or pagination state
- using
syncType: 'incremental'ornango.lastSyncDatein a new sync - using
trackDeletesStart()/trackDeletesEnd()with a changed-only checkpoint (modified_after,updated_after, changed-records endpoint). Those requests omit unchanged rows, sotrackDeletesEnd()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.mdbefore writing code
Sync:
- Scheduled or webhook-driven cache updates built with
createSync() - Complete the Sync Strategy Gate first
- Read
references/syncs.mdbefore 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, andurl/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, noaxios, 2 MB output limit). Use a proxy script in{integration}/proxy/with@nangohq/nodeinstead — seereferences/actions.md. - HTTP retries default to
0; setretriesdeliberately. Treat3as the normal maximum; for sync provider calls, values above3are 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
endpointand syncendpoints. 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
checkpointschema, callnango.getCheckpoint()first, andnango.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'ornango.lastSyncDate. - Default to
nango.paginate(...)+nango.batchSave(...). Avoid manualwhile (true)loops whencursor,link, oroffsetpagination 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.
deleteRecordsFromPreviousExecutions()is deprecated. For full refresh, calltrackDeletesStart()before fetch/save andtrackDeletesEnd()only after a successful full fetch/save.- Never combine
trackDeletesStart()/trackDeletesEnd()with changed-only checkpoints (modified_after,updated_after, changed-records endpoints, etc.). They omit unchanged rows, sotrackDeletesEnd()would delete them. - Checkpointed full refreshes are still full refreshes. Call
trackDeletesEnd()only in the run that finishes the full window. - If a sync requires metadata (e.g.
team_id,workspace_id,guild_id), setautoStart: 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
cursorplus 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 whennullhas 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 explicitnull,.nullish()only when the provider truly does both. - Final action outputs and normalized sync models should prefer
.optional()and normalize upstreamnullto omission unlessnullmatters. - Default generated schemas to
.optional()for non-required inputs and normalized outputs; widen only when the upstream contract justifies it. - Prefer
.nullable()overz.union([z.null(), T])orz.union([T, z.null()]). - Return
nullonly when the output schema allows it. z.object()strips unknown keys by default. For provider pass-through usez.object({}).passthrough(),z.record(z.unknown()), orz.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)
- Functions runtime SDK reference: https://nango.dev/docs/reference/functions
- Implement an action: https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
- Implement a sync: https://nango.dev/docs/implementation-guides/use-cases/syncs/implement-a-sync
- Checkpoints: https://nango.dev/docs/implementation-guides/use-cases/syncs/checkpoints
- Deletion detection (full vs incremental): https://nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection
- Testing integrations (dryrun,
--save, Vitest): https://nango.dev/docs/implementation-guides/platform/functions/testing - Nango HTTP API reference: https://nango.dev/docs/reference/api
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
Workflow (required)
- Decide whether this is an action or a sync.
- Read the matching reference file:
references/actions.mdorreferences/syncs.md. - For syncs, inspect provider docs or payloads for checkpoints and deletes, decide whether the endpoint returns full data or changed rows, and complete the Sync Strategy Gate.
- Gather required inputs and external values. For connection lookup, credentials, or discovery, use the Nango HTTP API.
- Confirm this is a Zero YAML TypeScript project (
no nango.yaml) and that you are in the Nango root (.nango/exists). - Create or update the function under
{integrationId}/actions/or{integrationId}/syncs/, apply the shared schema and casing rules, then register it inindex.ts. - Validate with
nango dryrun ... --validate -e dev --no-interactive --auto-confirm. - If validation cannot pass, stop and report the missing external state or inputs.
- After validation passes, run
nango dryrun ... --save, thennango generate:tests, thennpm test. - Deploy with
nango deploy devonly when requested.
Preconditions (Do Before Writing Code)
Confirm TypeScript Project (No nango.yaml)
This skill only supports TypeScript projects using createAction() / createSync().
ls nango.yaml 2>/dev/null && echo "YAML PROJECT DETECTED" || echo "OK - No nango.yaml"If you see YAML PROJECT DETECTED:
- Stop immediately.
- Tell the user to upgrade to the TypeScript format first.
- Do not attempt to mix YAML and TypeScript.
Reference: https://nango.dev/docs/implementation-guides/platform/migrations/migrate-to-zero-yaml
Verify Nango Project Root
Do not create files until you confirm the Nango root:
ls -la .nango/ 2>/dev/null && pwd && echo "IN NANGO PROJECT ROOT" || echo "NOT in Nango root"If you see NOT in Nango root:
cdinto the directory that contains.nango/- Re-run the check
- Do not use absolute paths as a workaround
All file paths must be relative to the Nango root. Creating files with extra prefixes while already in the Nango root will create nested directories that break the build.
Project Structure and Naming
./
|-- .nango/
|-- index.ts
|-- hubspot/
| |-- actions/
| | `-- create-contact.ts
| `-- syncs/
| `-- fetch-contacts.ts
`-- slack/
`-- actions/
`-- post-message.ts- Provider directories: lowercase (
hubspot,slack) - Action files: kebab-case (
create-contact.ts) - Sync files: kebab-case (many teams use a
fetch-prefix, but it is optional) - One function per file
- All actions and syncs must be imported in
index.ts
Register scripts in index.ts (required)
Use side-effect imports only. Include the .js extension.
// index.ts
import './github/actions/get-top-contributor.js';
import './github/syncs/fetch-issues.js';Symptom of incorrect registration: the file compiles but you see No entry points found in index.ts... or the function never appears.
Dryrun, Mocks, and Tests (required)
Required loop:
- Run
nango dryrun ... --validate -e dev --no-interactive --auto-confirmuntil it passes. - Actions: always pass
--input '{...}'(use--input '{}'for no-input actions). - Syncs: use
--checkpoint '{...}'when you need to simulate a resumed run. - If validation cannot pass, stop and state the missing external state or inputs required.
- After validation passes, run
nango dryrun ... --save -e dev --no-interactive --auto-confirmto generate<script-name>.test.json. - Run
nango generate:tests, thennpm test.
Examples:
# Validate an action
nango dryrun <action-name> <connection-id> --validate -e dev --no-interactive --auto-confirm --input '{"key":"value"}'
# Validate a no-input action
nango dryrun <action-name> <connection-id> --validate -e dev --no-interactive --auto-confirm --input '{}'
# Validate a sync
nango dryrun <sync-name> <connection-id> --validate -e dev --no-interactive --auto-confirm
# Validate a resumed sync with a checkpoint
nango dryrun <sync-name> <connection-id> --validate -e dev --no-interactive --auto-confirm --checkpoint '{"updated_after":"2024-01-15T00:00:00Z"}'
# Record action mocks after validation passes
nango dryrun <action-name> <connection-id> --save -e dev --no-interactive --auto-confirm --input '{"key":"value"}'
# Record sync mocks after validation passes
nango dryrun <sync-name> <connection-id> --save -e dev --no-interactive --auto-confirm
# Stub metadata when needed
nango dryrun <script-name> <connection-id> --validate -e dev --no-interactive --auto-confirm --metadata '{"team_id":"123"}'Hard rules:
- Treat
<script-name>.test.jsonas generated output. Never create, edit, rename, or move it. - If mocks are wrong or stale, fix the code and re-record with
--save. - Do not hard-code error payloads in
*.test.json; use a Vitest test withvi.spyOn(...)for 404, 401, 429, or timeout cases. - Connection ID is the second positional argument; do not use
--connection-id. - Use
--integration-id <integration-id>when script names overlap across integrations. - Prefer
--checkpointfor new incremental syncs;--lastSyncDateis a legacy pattern. - If
nangois not onPATH, usenpx nango .... - CLI upgrade prompts can block automation; set
NANGO_CLI_UPGRADE_MODE=ignoreif needed.
Reference: https://nango.dev/docs/implementation-guides/platform/functions/testing
Deploy (Optional)
Deploy functions to an environment in your Nango account:
nango deploy dev
# Deploy only one function
nango deploy --action <action-name> dev
nango deploy --sync <sync-name> devReference: https://nango.dev/docs/implementation-guides/use-cases/actions/implement-an-action
Final Checklists
Action:
- Nango root verified
references/actions.mdwas used for the action pattern- Schemas and types are clear, and missing-value rules match the provider versus normalized contract
createAction()includes input, output, and scopes when required; deprecatedendpointis omitted- Fields use passthrough casing or the API's majority casing
- Provider call includes an API doc link comment and intentional retries
nango.ActionErroris used for expected failures- Registered in
index.ts - Dryrun succeeds with
--validate -e dev --no-interactive --auto-confirm --input '{...}' <action-name>.test.jsonwas generated bynango dryrun ... --saveafter--validatenango generate:testsran andnpm testpasses
Sync:
- Nango root verified
references/syncs.mdwas used for the sync pattern- Models map is defined, ids are stable strings, and normalized models prefer
.optional()unlessnullmatters - Incremental was chosen first, with a checkpoint schema unless full refresh is explicitly justified from docs or payloads
nango.getCheckpoint()is read at the start andnango.saveCheckpoint()runs after each page or batch- Checkpoint data changes the provider request or resume state (
since,updated_after,cursor,page_token,offset,page,since_id, etc.) - Changed-only checkpoint syncs (
modified_after,updated_after, changed-records endpoint) do not usetrackDeletesStart()/trackDeletesEnd() - If checkpoints were not used, the response explains exactly why no viable checkpoint strategy exists
- Raw provider schemas model omitted versus
nullcorrectly, and fields use passthrough casing or the API's majority casing nango.paginate()is used unless the API truly cannot fit Nango's paginator- Provider API calls use
retries: 3; no sync retry value exceeds3without a documented exception - Deletion strategy matches the sync type:
batchDelete()for incremental only when the provider returns explicit deletions; otherwise full-refresh fallback usestrackDeletesStart()before fetch/save andtrackDeletesEnd()only after a successful full fetch plus save - Metadata handled if required
- Registered in
index.ts - Dryrun succeeds with
--validate -e dev --no-interactive --auto-confirm <sync-name>.test.jsonwas generated bynango dryrun ... --saveafter--validatenango generate:testsran andnpm testpasses
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

