Scripts are a key differentiator of Nango, enabling you to customize interactions with external APIs. Running on Nango’s infrastructure, these scripts can be Nango-provided templates or your own implementations.
Scripts are associated with a specific integration, and they apply to all the connections of this integration.For example, if you create a sync script to sync issues from GitHub, by default, it will run for all past & future connections of your GitHub integration.However, you have the flexibility to customize this behavior per connection, including starting or pausing syncs and adjusting sync schedules.You can monitor script execution times and configure script options directly in the Nango UI:
Execution time: Available for each connection, helping you understand the performance and efficiency of your scripts.
Configuration options: Found under the integration Scripts tab.
Scripts reside in a dedicated integration folder, which should be version-controlled.You’ll develop these scripts using the CLI, which assists in scaffolding, compilation, and deployment.
Scripts provide access to a nango object (reference), providing helper methods for API requests, data persistence, logging, and access to connection specifics. Scripts can also access environment variables that you configure in the Environment Settings tab of the Nango UI.
Scripts should be somewhat CPU and memory-efficient to prevent operational issues (cf. recommendations). They execute within a runner VM allocated to your Nango workspace, which has specified limits on memory and CPU usage. Exceeding these limits can cause crashes or delays in processing actions and syncs. Opting for paid plans grants access to VMs with enhanced resources and auto-scaling capabilities for better performance.
You should test your scripts locally to ensure they function as expected (using the CLI). Once verified, they are deployed to Nango’s cloud infrastructure, where they operate across different environments.Upon deployment, scripts are stored in blob storage. The Nango runner loads and executes these scripts as needed (architecture).
For both syncs and actions, the nango.yaml specifies what data goes in and out, alongside the specifications for the endpoints that will handle data synchronization or action triggers.Specifically for syncs, it details the schedule for syncing operations, whether the syncs use the incremental or full refresh mode, and how deletions are handled.Webhook configurations are also detailed in this file, outlining the subscription mechanisms for receiving updates from external APIs.
When developing a new script, your first step should be to define it in the nango.yaml file. Following this, you can use the CLI to generate the necessary script scaffolding (step-by-step guide).After deploying changes to your integration configuration to a Nango cloud environment, these updates will be visible within the Nango UI under the integration’s Scripts tab, ensuring you have a clear overview of the configurations in effect for your integrations.Any changes you make in the nango.yaml affect all connections under that integration. For instance, modifying the sync schedule for tasks in an Asana integration from daily to hourly will adjust the frequency for all linked Asana connections.
The Nango Command-Line Interface (CLI), installed via npm, lets you generate, compile, test, and deploy integration scripts & configuration. For a detailed installation guide, refer to the step-by-step guide.
The nango-integrations folder is generated via the Nango CLI and governs the communication between Nango & external APIs (while your app’s code governs the communication between your app and Nango).
You should version-control the nango-integrations folder, either with your main codebase or separately. Ensure the .env file is excluded to protect your API keys.
For those using Nango’s managed integration service, Nango team contributions to the nango-integrations folder come via PRs in a shared GitHub repository. These PRs contain updates or new integrations that you can merge and deploy.
Each script creates one or more endpoints within Nango, as defined in your integration configuration. This setup facilitates the consolidation of endpoints from various APIs into a single, unified Nango endpoint, streamlining API interactions.Nango dynamically generates references for these endpoints, accessible via the API Reference tab in the integration section of the Nango UI. Once scripts are enabled — whether templates or custom — you can utilize Nango’s unified API without needing detailed knowledge of the script internals. This abstraction simplifies API consumption, making it more accessible and manageable.
Questions, problems, feedback? Please reach out in the Slack community.
