Skip to main content
The sample app contains:
  • A frontend: lets users connect an integration using the Nango frontend SDK.
  • A backend: listens to Nango webhooks and consumes the Nango API to read & write data.
The sample app uses Slack, Google Drive, OneDrive for Business, and OneDrive Personal as example integrations and is showcased in this demo video.

​
Access the repository

NangoHQ/sample-app

​
Run the sample app

1

Create an account

  • Go to nango.dev and create an account (free).
2

Create a Slack integration

  • Go to Integrations and create a Slack integration.
  • Set up a Slack app:
    1. Go to Slack Dev Center and click Create New App.
    2. Select From scratch for a simpler flow.
    3. Enter your App Name and select a workspace to develop your app in, then click Create App.
    4. In the Basic Information tab, copy your Client ID and Client Secret.
    5. Go to OAuth & Permissions in the left sidebar.
    6. Under Redirect URLs, add https://api.nango.dev/oauth/callback and click Save URLs.
    7. Under Scopes > Bot Token Scopes, add:
      • users:read
      • chat:write
  • Go back to Nango. In the Authorization tab, add:
    • client_id: from step 4
    • client_secret: from step 4
  • In the Endpoints tab, activate GET /users and POST /send-message.
3

Create a Google Drive integration

  • Go to Integrations and create a Google Drive integration.
  • Set up a Google Cloud project:
    1. Go to the Google Cloud Console and create a new project (or select an existing one).
    2. Go to the API Library, search for Google Drive API, and click Enable.
    3. Go to APIs & Services > OAuth consent screen and configure it:
      • Select External user type (or Internal for users within your Google Workspace organization).
      • Fill in the required app information and contact information.
      • Add the scope: https://www.googleapis.com/auth/drive.readonly.
      • Add test users if using External user type.
    4. Go to APIs & Services > Credentials > Create Credentials > OAuth client ID.
    5. Select Web application, enter a name, and add https://api.nango.dev/oauth/callback under Authorized redirect URIs.
    6. Click Create and copy the Client ID and Client Secret.
    7. Copy the Project Number from the Google Cloud console under IAM & Admin > Settings > Project Number.
  • Go back to the Google Drive integration in Nango. In the Authorization tab, add:
    • client_id: from step 6
    • client_secret: from step 6
    • scopes: https://www.googleapis.com/auth/drive.readonly
  • In the Endpoints tab, activate GET /documents endpoint.
4

Create a OneDrive for Business integration

  • Go to Integrations and create a OneDrive for Business integration.
  • Register an application in Microsoft Entra admin center:
    1. Sign in to the Microsoft Entra admin center and search for App registrations > New registration.
    2. Enter a name (e.g., “Nango OneDrive Integration”).
    3. Under Supported account types, select Accounts in any organizational directory for multitenant apps.
    4. Click Register and note the Application (client) ID from the Overview page.
    5. Go to Authentication > Add a platform > Web and add https://api.nango.dev/oauth/callback as the Redirect URI.
    6. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions and add Files.Read.All.
    7. Go to Certificates & secrets > New client secret, create a secret, and copy the value immediately (you won’t see it again).
  • Go back to the OneDrive for Business integration in Nango. In the Authorization tab, add:
    • client_id: Application (client) ID from step 4
    • client_secret: Client secret value from step 7
    • scopes: Add offline_access and .default
  • In the Endpoints tab, activate GET /user-files/selected endpoint.
5

Create a OneDrive Personal integration

  • Go to Integrations and create a OneDrive Personal integration.
  • Register an application in Microsoft Entra admin center:
    1. Sign in to the Microsoft Entra admin center and search for App registrations > New registration.
    2. Enter a name (e.g., “Nango OneDrive Personal Integration”).
    3. Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
    4. Click Register and note the Application (client) ID from the Overview page.
    5. Go to Authentication > Add a platform > Web and add https://api.nango.dev/oauth/callback as the Redirect URI.
    6. Go to Certificates & secrets > New client secret, create a secret, and copy the value immediately (you won’t see it again).
  • Go back to the OneDrive Personal integration in Nango. In the Authorization tab, add:
    • client_id: Application (client) ID from step 4
    • client_secret: Client secret value from step 6
    • scopes: Add offline_access and onedrive.readonly
  • In the Endpoints tab, activate GET /user-files/selected endpoint.
6

Prepare your env

  • Install: NodeJS, Docker. Then run:
git clone https://github.com/NangoHQ/sample-app.git

cd sample-app

nvm use
npm i
  • Copy your Nango Secret Key, found in Environment Settings.
  • Create a file to store environment variables and fill in the Nango Secret Key:
cp .env.example .env
  • Paste the Project Number you copied in step 7 of the Google Drive integration setup into the .env file as GOOGLE_PROJECT_NUMBER=your_project_number_here:
cd front-end
cp .env.example .env
7

Transfer Nango webhooks locally

  • This command should be running at all time:
npm run webhooks-proxy
  • Copy the URL the command gave you and go to Environment Settings. Set Webhook URL to ${URL}/webhooks-from-nango, e.g: https://tame-socks-warn.loca.lt/webhooks-from-nango.
8

Launch

  • Run:
npm run start
9

Bonus: Deploy custom functions

The above sample app uses pre-built functions, but you can also use custom ones.
  • Set up the Nango CLI:
npm install -g nango
cd nango-integrations/
nango init
  • Add your Nango Secret Key in NANGO_SECRET_KEY_PROD in ./nango-integrations/.env.
  • Optionally customize the functions using this guide.
  • Deploy the custom functions:
nango deploy prod

​
File Integration Guide

The sample app includes a complete implementation for integrating file storage providers (Google Drive, OneDrive) with your application. This guide walks you through using and understanding the file integration features.

​
Overview

Nango’s pre-built file integration allows you to:
  1. OAuth Flow: Handle authentication using Nango’s SDK
  2. File Picker: Let users select specific files and folders to sync
  3. Document Sync: Sync metadata for selected files and folders
  4. Document Fetching: Download individual file contents as needed

​
Requirements

  • Docker (desktop) installed & running
  • NodeJS & NPM installed
  • A Nango account (sign up at nango.dev)
  • Integration setup completed (see steps above)

​
Using the File Integration

After setting up and running the sample app (see steps above), follow these instructions to test the file integration:
  1. Access the sample app: Sample app home page with Files section highlighted
  2. Connect your account (Google Drive, OneDrive, etc.):
    • Click the Connect button on the provider’s card
    • In the connection popup, click the Connect button
    • Select your account and authorize the app
    • Click the Finish button to close the modal
    Connect popup with file provider account options Successfully connected to file provider
  3. Select files and folders to sync:
    • Click the Select Files from [Provider] button
    • A file picker modal will appear - note that each provider has its own native file picker:
      • Google Drive: Uses Google’s Drive Picker UI
      • OneDrive for Business: Uses Microsoft’s file picker for organizational accounts
      • OneDrive Personal: Uses Microsoft’s file picker for personal accounts
    • Select the files and folders you want to sync using the provider’s file picker
    • Click the Select button to confirm your selection
    Select files and folders from provider Select files and folders from provider
  4. View synced files:
    • The files and folders will be synced to your Nango account and displayed in the UI
    Synced files and folders in the UI
  5. Download a file:
    • Click the Download button to download the file to your computer
  6. Disconnect your account:
    • Click the Disconnect button to disconnect your account and delete your connection from your Nango account
    Disconnect button

​
What Happens Under the Hood

The sample app uses Nango to:
  1. Authentication
    • Authenticate users with file storage providers
    • Show the file picker
    • Handle OAuth flow automatically
  2. File Syncing
    • Sync selected files & folders
    • Initial sync on selection
    • Periodic updates
    Nango dashboard showing sync status and file list
  3. File Download
    • Download raw file content
    • Handle different file types
    • Use Nango’s proxy for reliable downloads

​
Key Components

​
Frontend Implementation

  1. Authorization Flow The authorization process is implemented in front-end/src/api.ts:
    • postConnectSession: Initiates the OAuth connection
    • getNangoCredentials: Retrieves credentials after successful authorization
    The flow works as follows:
    1. Frontend initiates connection via postConnectSession
    2. Backend creates a Nango connection session
    3. User is redirected to provider OAuth consent screen
    4. After authorization, user is redirected back to the app
    5. User is shown the provider-specific file picker (Google Drive Picker, OneDrive for Business picker, or OneDrive Personal picker)
    6. Frontend can fetch credentials using getNangoCredentials

​
Backend Implementation

  1. Webhook Handler & Data Sync The webhook handling and data sync logic is implemented in back-end/src/routes/postWebhooks.ts: Key components:
    • Main webhook handler that verifies signatures and routes requests
    • handleNewConnectionWebhook: Processes new file provider connections
    • handleSyncWebhook: Handles sync completion and data processing
    The sync process:
    1. Nango syncs files from the provider
    2. Webhook notifies backend of sync completion
    3. Backend fetches records using nango.listRecords
    4. File metadata is stored in the database
    5. Deletions are tracked and handled appropriately
  2. File Download with Proxy File download functionality is implemented in back-end/src/routes/downloadFile.ts: The download process:
    1. Frontend requests file download with file ID and connection ID
    2. Backend uses Nango proxy to fetch file from provider
    3. File is streamed to client with proper headers
    4. Error handling ensures graceful failure
    Key features:
    • Uses Nango proxy for secure file access
    • Proper content type and disposition headers
    • Streaming response for efficient file transfer
    • Comprehensive error handling

​
Nango Dashboard

Explore these sections in your Nango account:
  1. Integration Settings
  2. Connections
  3. Logs
    • View Logs
    • Track sync operations
    • Debug issues

​
Common Issues and Solutions

  1. Connection Issues
    • Check Docker is running
    • Verify webhook URL is correct
    • Ensure provider credentials are valid
  2. Sync Problems
    • Check Nango logs
    • Verify file permissions
    • Monitor sync status

​
File Type Support

The sample app supports all file types through Nango’s proxy:
  • Regular files (PDFs, images, documents, etc.)
  • Google Workspace files (Docs, Sheets, Slides)
  • Microsoft Office files (Word, Excel, PowerPoint)
  • Other cloud storage file types
Questions, problems, feedback? Please reach out in the Slack community.