Merge.dev Connection Plugin

The Merge.dev Connection Plugin enables users to sync data from hundreds of third-party integrations directly into Flatfile through the Merge.dev unified API platform. When a user establishes a connection to a service via Merge within the Flatfile UI, the plugin automatically creates a new Flatfile Workbook with a schema that matches the data models for that integration. The plugin performs an initial data sync and allows users to manually trigger full data refreshes at any time.

​

Installation

Install the plugin using npm:

npm install @flatfile/plugin-connect-via-merge

​

Configuration & Parameters

This plugin is configured through Flatfile Secrets rather than code-based options.

​

Required Secret

​

Function Signature

The plugin exports a single function:

mergePlugin(): (listener: FlatfileListener) => void

Parameters: None

Returns: A function that registers job handlers with the Flatfile listener for:

• space:createConnectedWorkbook: Creates workbooks based on Merge schemas
• workbook:syncConnectedWorkbook: Syncs data from connected services

​

Usage Examples

import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // Add the Merge.dev plugin to the listener
  listener.use(mergePlugin());
}

​

Complete Setup Example

import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // Register the Merge.dev plugin handlers
  listener.use(mergePlugin());

  // Add other listeners as needed
  listener.on('**', (event) => {
    console.log(`Event received: ${event.topic}`);
  });
}

​

Configuration Setup

1. Create the Secret: In your Flatfile Space settings, create a new Secret with the name MERGE_ACCESS_KEY and your Merge.dev API key as the value.

2. Use the Plugin: The plugin automatically looks for the MERGE_ACCESS_KEY secret in the Space where it’s running.

import { FlatfileListener } from "@flatfile/listener";
import { mergePlugin } from "@flatfile/plugin-connect-via-merge";

export default function (listener) {
  // The plugin automatically uses the 'MERGE_ACCESS_KEY' secret
  listener.use(mergePlugin());
}

​

Troubleshooting

​

Missing API Key Error

If you encounter errors related to missing Merge API keys, ensure that:

1. The MERGE_ACCESS_KEY secret is properly set in your Flatfile Space
2. The API key value is correct and active in your Merge.dev account

​

Sync Timeout Issues

If sync operations timeout, the plugin polls Merge.dev for up to 5 minutes (30 attempts at 10-second intervals). If Merge doesn’t complete its sync within this window, the job will fail with a timeout error.

​

Job Failures

Check the Flatfile Job logs in your dashboard for specific error messages. The plugin provides descriptive error messages for common issues like missing credentials or API failures.

​

Notes

​

Prerequisites

• The connections feature flag must be enabled for your Flatfile account (contact support@flatfile.com)
• Active Merge.dev account required
• MERGE_ACCESS_KEY secret must be configured in your Flatfile Space

​

Alpha Release Warning

This plugin is an alpha release. Functionality and APIs may change in future versions.

​

Data Sync Behavior

• Each sync performs a full refresh of data
• All existing records are deleted before inserting current data
• Manual changes made in Flatfile will be overwritten on next sync
• This ensures data consistency with the source system

​

Automatic Secret Management

The plugin automatically creates workbook-specific secrets named <workbookId>:MERGE_X_ACCOUNT_TOKEN to store account tokens for each connection. These are managed internally by the plugin.

​

Error Handling Pattern

The plugin uses centralized error handling that:

• Logs original errors to the console for debugging
• Throws user-friendly error messages displayed in the Flatfile UI
• Causes failed jobs to show descriptive error messages in the dashboard

​

Manual Sync Actions

After initial setup, the plugin automatically adds a “Sync” action to connected workbooks. Users can trigger this action from the Flatfile UI to refresh data without additional code.