Skip to main content
Functions are Nango’s TypeScript runtime for building custom integrations. You write integration logic in TypeScript, deploy it to Nango, and it executes with built-in access to authenticated APIs, retries, storage, and observability. Every function execution is tied to a connection — the API credentials for a specific user and integration. Nango resolves credentials, handles token refresh, and injects them automatically, so your code never manages secrets directly.

​
Function types

Syncs

Continuously fetch and cache data from external APIs on a schedule. Ideal for keeping a local copy of contacts, files, or any external records up to date.

Actions

On-demand functions that write data or execute operations on external APIs. Triggered explicitly from your backend and return a typed result.

Webhook processing

Handle incoming webhooks from external APIs reliably. Nango routes, deduplicates, and attributes each webhook to the right connection.

Proxy

Make authenticated API requests without managing credentials. Nango injects auth, retries, and logs every call automatically.

​
How functions work

export default async function run(nango: NangoAction) {
    const { owner, repo, title, body } = nango.input;

    const response = await nango.post({
        endpoint: `/repos/${owner}/${repo}/issues`,
        data: { title, body }
    });

    return response.data;
}
The nango object is the runtime SDK available inside every function. It provides authenticated HTTP methods, logging, metadata storage, checkpointing, and more — all scoped to the connection the function is executing for.

​
The function lifecycle

1

Write

Create a TypeScript file in your nango-integrations folder. Use createSync or createAction to define your function with typed inputs, outputs, and configuration.
2

Test

Run nango dryrun <function-name> <connection-id> to execute your function locally against a real connection. Data is printed to the console without being persisted.
3

Deploy

Run nango deploy dev to deploy your functions to Nango. Most teams automate this step in CI/CD.
4

Execute

Functions are triggered by API calls, schedules, incoming webhooks, or connection lifecycle events. Results and logs appear in the Nango dashboard.

​
Built-in capabilities

​
Authenticated API access

Every function receives a nango object pre-bound to the current connection. Call nango.get(), nango.post(), nango.put(), nango.patch(), or nango.delete() and credentials are injected automatically — including OAuth token refresh.

​
Retries and rate-limit handling

Pass retries: N to any proxy call and Nango retries with exponential backoff. Rate-limit responses (429s) are handled transparently.

​
Storage

Syncs write records to Nango’s encrypted cache using nango.batchSave(). Records are change-tracked: Nango detects additions, updates, and deletes, then notifies your backend via webhook.

​
Checkpoints

Save progress mid-execution with nango.saveCheckpoint() and resume from the same point on the next run. This makes long-running syncs resilient to failures without re-fetching everything.

​
Observability

All function executions and individual API requests are logged. Use nango.log() to emit custom messages. Logs are visible in the Nango dashboard and exportable via OpenTelemetry.

​
Connections and functions

Each function execution is scoped to a single connection. A connection represents one user’s credentials for a given integration (e.g., a specific GitHub account linked to your app). When Nango runs a sync, it runs the same function code once per connection, keeping customer data fully isolated.

​
Setup

1

Install the CLI

npm install -g nango
2

Initialize your integrations folder

nango init nango-integrations
This creates a nango-integrations/ directory with an example sync and initial configuration. Commit this folder to version control.
3

Authenticate the CLI

Add your secret keys to nango-integrations/.env:
NANGO_SECRET_KEY_PROD='<PROD-SECRET-KEY>'
NANGO_SECRET_KEY_DEV='<DEV-SECRET-KEY>'
Get your secret keys from Environment Settings in the Nango dashboard.
4

Start dev mode

nango dev
This starts a process that continuously compiles your functions and prints syntax errors as you develop.
Install the AI function builder skill to generate functions from natural language descriptions: npx skills add NangoHQ/skills. See the AI builder guide for details.

​
Next steps

AI builder

Generate integration code from a plain-language description of what you want to build.

Syncs

Build a continuously running function that fetches and caches external API data.

Actions

Build an on-demand function that writes data or triggers operations on external APIs.

Proxy

Make ad-hoc authenticated API requests without deploying a function.

Build docs developers (and LLMs) love

Get started for freeTalk to us