Deploying to Flatfile

Learn how to deploy your code to Flatfile.

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For a production deployment, listeners can be hosted either in your cloud or directly on the Flatfile platform.

Hosting on the Flatfile platform (recommended)

While your own cloud provides the maximum level of control over listener code, qualities such as availability and network performance are the responsibility of the hosting provider. Listeners may be securely deployed and run in the Flatfile platform cloud giving you a more consistent, low-latency, high-availability experience.

Deploying a Workbook to Flatfile from terminal

Once you have configured your Workbook, you can deploy your Workbook to your account at any time by opening the terminal in the root directory and entering this command:

Add the file name to the command: npx flatfile deploy path-to-file if you’re not running an index file.

terminal

npx flatfile@latest deploy --token=YOUR_SECRET_KEY

The CLI will give you prompts and updates as it’s deploying:

> npx flatfile@latest deploy --token=sk_123456

✔  Code package compiled to .flatfile/build.js
✔  Code package passed validation
✔  Environment "Default" selected
✔  Event listener deployed and running on your environment "Default". us_ag_1234

See it in your Dashboard

Once your Workbook has been deployed, you’ll be able to see a new Space in your Dashboard. Your Workbook will be added to every Space you create.

You can also configure your code to build different Workbooks as a Space is created depending on various factors. Learn about Dynamic Configurations.

Redeploying

You can deploy any change to your code at any time.

For example, if you need to add a Sheet to an already existing Workbook, simply deploy again with the added Sheet and everything will update.

Deploying multiple agents

To deploy a second Agent without overwriting the first, you can specify a slug for the Agent:

npx flatfile@latest deploy -s my-second-agent

When you deploy with a slug, the CLI will create a new Agent with the specified slug. This allows you to deploy multiple Agents to the same environment.

To update an existing Agent, you can specify the slug of the Agent you want to update by running the same command, including the slug.

If you do not specify a slug and have only one or no deployed Agents the CLI will update your existing Agent, or create your first Agent. The slug for this agent will be default.

Hosting on Regional Servers

Regional servers are available upon request for those needing to host their applications closer to their user base, ensuring faster access and compliance with local data regulations. To deploy on a regional server, please contact our support team.

URL References

Region	URL	API URL	SPACE URL
UK	https://platform.uk.flatfile.com/	https://platform.uk.flatfile.com/api	https://platform.uk.flatfile.com/
EU	https://platform.eu.flatfile.com/	https://platform.eu.flatfile.com/api	https://platform.eu.flatfile.com/
AU	https://platform.au.flatfile.com/	https://platform.au.flatfile.com/api	https://platform.au.flatfile.com/
CA	https://platform.ca.flatfile.com/	https://platform.ca.flatfile.com/api	https://platform.ca.flatfile.com/

Configuring the API URL for Deployment

When deploying, you can specify the FLATFILE_API_URL either in your project’s .env file or as an environment variable.

Deploy command example

npx flatfile@latest deploy

Embedding with a Specific API URL

To embed Flatfile in your application, include both apiUrl and spaceUrl in your FlatfileImporter configuration to specify your regional server:

const spaceProps: ISpace = {
  name: "Embedded Space",
  publishableKey: "pk_**********",
  apiUrl: "Regional API URL here",
  spaceUrl: "Regional Space URL here", //Optional, only needed if reusing a space
  workbook,
  listener,
  // Additional properties here
};

API Interaction with a Specified Environment

For direct API interactions, the FlatfileClient needs the environment parameter set to your selected regional API URL:

import { FlatfileClient } from "@flatfile/api";

const api = new FlatfileClient({
  environment: "Regional API URL here",
});

Hosting in your own cloud

Hosting listener code in your own cloud works similarly to how we run the develop command in that:

1. The listener process is launched
2. It polls the Flatfile API for updates
3. It then responds to those Events accordingly

Reach out to support for learning how about hosting in your own cloud.