Running on your local machine

Learn how to develop with Flatfile CLI.

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!

When developing with Flatfile, listeners can deployed to Flatfile on every change or they can run directly on your machine.

Before you begin

You can add a .env file to bypass having to enter your API Key when running the develop command.

FLATFILE_API_KEY=sk_123456

Develop

Run npx flatfile develop from terminal to launch a local listener. As your code changes, file changes are detected and will be reflected immediately.

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

1. In your terminal, you’ll see a detailed log of each HTTP request made within a listener. It includes the request timing and status, enabling tracking and debugging of HTTP operations.
2. A pub/sub stream system will deliver Events with a latency of approximately 10-50ms. This provides a local development experience closely resembling the production environment speed.
3. Events that are being processed will be shown, along with their respective handlers. You can then respond to those Events accordingly.

> npx flatfile develop
✔ 1 environment(s) found for these credentials
✔ Environment "development" selected
ncc: Version 0.36.1
ncc: Compiling file index.js into CJS
  ✓ 427ms      GET    200 https://platform.flatfile.com/api/v1/subscription 12345

 File change detected. 🚀
  ✓ Connected to event stream for scope us_env_1234
 ▶ commit:created  10:13:05.159 AM us_evt_1234
 ↳ on(**, {})
 ↳ on(commit:created, {"sheetSlug":"contacts"})

Shared environments

It is highly recommended to utilize an isolated environment when developing with the local listener. That’s why the CLI is warning you when working in an environment that already has a deployed agent.

Check for existing agents

Create a new isolated environment in dashboard

More details

Having deployed code running at the same time within the same development environment can lead to interference, potentially resulting in a recursive loop and undesirable consequences for your local listener. To avoid such complications, it’s advisable to keep your local environment separate from any deployed code. This ensures optimal performance and helps maintain a stable development environment.