Skip to main content
Building custom integrations for Nango is much faster when using AI tools. This guide shows you how to leverage Cursor or Claude Code to build high-quality integrations quickly. We recommend using one of these AI-powered development environments:
  • Cursor with Agent Mode
  • Claude Code (Anthropic’s official CLI tool)
Both tools understand Nango’s architecture and can help you build integrations following best practices.

​
Prerequisites

Before starting, ensure you have:
  1. Finished the initial Functions setup
  2. At least one integration configured in your Nango environment
  3. A test Connection for the integration you want to develop for

​
Step-by-step process

​
1. Set up your development environment

First, make sure your Nango project is properly initialized: 
# If you don't have a nango-integrations folder yet
nango init --ai cursor

# Navigate to your integrations directory
cd nango-integrations

# Ensure your environment is configured
# Check that .env contains your NANGO_SECRET_KEY_DEV
# Get your dev secret from: https://app.nango.dev/dev/environment-settings

​
2. Craft effective prompts

When working with your AI assistant, provide clear, specific prompts: Example prompt structure: 
I need to build a Nango custom [SYNC/ACTION] for [API_NAME] called [INTEGRATION_NAME].

## Context
- Provider: [api-name]
- Integration: [integration-name]
- Type: [sync/action]
- Test connection ID: [connection-id]

## Additional details
- **Output schema**: [describe the expected data structure]
- **Field mapping**:
  - `api_field_name` → `nango_field_name`
  - other transformations (e.g., dates)
- **API Documentation**: [link-to-docs]
- **Data source**: [specific API endpoint(s) to call]
- **Error handling requirements**

Please implement this step by step and use `nango dryrun <integration-name> <connection-id> --validation [--input '{...}']` to test.

​
3. Key prompt tips

  • Be specific about the provider and integration name—this helps the AI understand the context
  • Specify sync vs action—clearly state whether you’re building a sync (continuous data synchronization) or action (one-time operation)
  • Specify data models—clearly describe what data you want to be synced or returned and its structure
  • Include field mapping details—specify how API fields should map to your desired output schema and any transformations needed
  • Provide the test connection ID—enables the AI to run nango dryrun for testing
  • Include API documentation links—if available, provide links to the provider’s API docs

​
4. Iterative Development

Work with your AI assistant iteratively:
  1. Start with basic data fetching
  2. Test with nango dryrun
  3. Add data transformation and validation
  4. Implement error handling
  5. Add pagination if needed
  6. Final testing and cleanup

​
Common pitfalls and checklist

When using AI to build integrations, watch out for these common issues:

​
❌ API Knowledge Gaps

  • Problem: AI may not know specific API endpoints/parameters or may use non-existent endpoints
  • Solution: Provide API documentation and verify endpoint usage against the actual API docs
  • Watch for: Endpoints that don’t exist in the provider’s API, client-side filtering instead of using proper query parameters

​
❌ Code Artifacts

  • Problem: Leftover debugging code or incomplete implementations
  • Solution: Review generated code thoroughly and ask AI to clean up artifacts

​
❌ Missing Validation

  • Problem: No input validation or data type checking
  • Solution: Explicitly ask for validation of API responses and input parameters

​
❌ Poor Error Handling

  • Problem: Basic or missing error handling for API failures or missing data
  • Solution: Request comprehensive error handling for common API error scenarios

​
✅ Quality checklist

Before finalizing your integration, verify:
  • API endpoints are correctly implemented
  • Proper query parameters are used
  • All debugging code and artifacts are removed
  • Input and output validation is implemented
  • Error handling covers common failure scenarios
  • Pagination is implemented correctly
  • Data models match the expected schema
  • nango dryrun passes successfully and without errors

​
When to restart with fresh context

Consider starting with a fresh AI context when:
  • The conversation becomes too long and the AI loses track of requirements
  • Multiple failed attempts have cluttered the context
  • The AI starts suggesting irrelevant or incorrect solutions
Save working code snippets before restarting, so you can quickly provide context to the fresh session.

​
Best practices for AI-assisted development

  1. Start simple: Begin with basic functionality and iterate
  2. Test frequently: Ensure the agent is running nango dryrun after each significant change
  3. Provide feedback: Give clear feedback on what works and what doesn’t
  4. Stay focused: Keep prompts focused on specific tasks
  5. Review thoroughly: Always review AI-generated code before deploying