Handling Large Listeners

Last updated: April 21, 2025

For large projects with many listeners, it's more performant to combine them together into one single listener/agent rather than deploy and maintain multiple agents. However, this can create a new problem in that the file size can grow too large and maintainability becomes an issue.

Here's a brief example of a listener that includes all the code in one file.

import { FlatfileEvent, FlatfileListener } from "@flatfile/listener";
import { FlatfileRecord, bulkRecordHook } from "@flatfile/plugin-record-hook";
import { xlsxExtractorPlugin } from '@flatfile/plugin-xlsx-extractor'
import { exportWorkbookPlugin } from "@flatfile/plugin-export-workbook";

// Example listener file that includes all the listeners in one. As the code
// logic increases, the files size grows to thousands of lines and makes it 
// hard to maintain. This file just has a few listeners but could contain 
// hundreds of listeners. It is preferable from a performance perspective to
// group all the listeners together like this than to deploy each listener
// separately but then managing such a large file becomes an issue.

export default function (listener: FlatfileListener) {

  listener
    .filter({ job: "space:configure" })
    .on("job:ready", async (event: FlatfileEvent) => {
      // space configuration code here
    });

  listener.use(
    bulkRecordHook("contacts", async (records: FlatfileRecord[], event) => {
      records.map((record) => {
        // recordHook code here
      })
    })
  );

  listener
    .filter({ job: "workbook:submit" })
    .on("job:ready", async (event: FlatfileEvent) => {
      // submission code here
    });

  listener.use(xlsxExtractorPlugin({ rawNumbers: true }))

  listener.use(exportWorkbookPlugin());

}

Here are some examples of how you might segment out your listener code while still deploying it once to get both performance and maintainability.
​

listener.ts

import { FlatfileListener } from "@flatfile/listener";
import { xlsxExtractorPlugin } from '@flatfile/plugin-xlsx-extractor'
import { exportWorkbookPlugin } from "@flatfile/plugin-export-workbook";
import { spaceConfigure } from "./listeners/space.configure"
import { recordHooks } from "./listeners/recordHooks"
import { submitWorkbook } from "./listeners/submitWorkbook"

// An improved listener file that still includes all the listeners in a single
// file for performance reasons but breaks out each listener's code to a separate
// file to improve code maintenance.

export default function (listener: FlatfileListener) {

  listener.use(spaceConfigure);
  listener.use(recordHooks);
  listener.use(submitWorkbook);
  listener.use(xlsxExtractorPlugin({ rawNumbers: true }))
  listener.use(exportWorkbookPlugin());

}

recordHooks.ts

import { FlatfileEvent, FlatfileListener } from "@flatfile/listener";
import { FlatfileRecord, bulkRecordHook } from "@flatfile/plugin-record-hook";

export function recordHooks(listener: FlatfileListener) {
  listener
    .use(
      bulkRecordHook("contacts", async (records: FlatfileRecord[], event) => {
        records.map((record) => {
          // recordHook code here
        })
      })
    );
}

space.configure.ts

import { FlatfileEvent, FlatfileListener } from "@flatfile/listener";

export function spaceConfigure(listener: FlatfileListener) {
  listener
    .filter({ job: "space:configure" })
    .on("job:ready", async (event: FlatfileEvent) => {
      // space configuration code here
    })
}

submitWorkbook.ts

import { FlatfileEvent, FlatfileListener } from "@flatfile/listener";

export function submitWorkbook(listener: FlatfileListener) {
  listener
    .filter({ job: "workbook:submit" })
    .on("job:ready", async (event: FlatfileEvent) => {
      // submission code here
    });
}