Failpath Quickstart: Instrument and Publish Your First Flow

This guide walks you through everything you need to go from zero to a live, monitored flow on the Failpath dashboard. By the end, your backend functions will be sending real-time step events that you can watch and debug from a single place.

Create a project

Sign in to failpath.dev and create a new project. Once the project is created, copy your project key — it looks like fp_project_xxx. You’ll use it in the next step to connect your repository.

Initialize your repository

Run failpath init at the root of your repository, passing your project key:

npx failpath init --project-key fp_project_xxx

The init command sets up everything Failpath needs in your repo:

File	What it does
`.env`	Writes `FAILPATH_PROJECT_KEY=fp_project_xxx` so the CLI and SDK can read your project key locally
`.failpath/flows.json`	Pulls your project’s current flow graph from the dashboard
`.failpath/sdk.ts`	Generates typed flow and step key bindings for autocomplete
`.failpath/AGENTS.md`	Provides step-key guidance for instrumenting your code correctly
`.gitignore`	Updated to exclude `.env` from version control

Install the SDK

Add @failpath/sdk to your backend project using your preferred package manager:

npm install @failpath/sdk

yarn add @failpath/sdk

pnpm add @failpath/sdk

bun add @failpath/sdk

Instrument a function

Import createTypedFailpathClient and failpathFlows from the generated .failpath/sdk.ts helper, then wrap your backend logic with run() and step(). Adjust the relative import path to match where your client file lives.The example below instruments a checkout handler with two steps:

import { createTypedFailpathClient, failpathFlows } from "../.failpath/sdk";

const failpath = createTypedFailpathClient({
  projectKey: process.env.FAILPATH_PROJECT_KEY!,
});

export async function handleCheckout(requestId: string) {
  const run = failpath.run(failpathFlows.checkout.slug, { runId: requestId });

  const cart = await run.step(failpathFlows.checkout.steps.validateCart, async () => {
    return validateCart();
  });

  await run.step(failpathFlows.checkout.steps.chargeCard, async () => {
    return chargeCard(cart);
  });

  await failpath.flush();
}

Each call to step() queues a running event before the wrapped function executes, then queues a success or error event when it completes. Telemetry sends in the background by default. Call flush() before a short-lived process exits, or use a platform waitUntil hook when your runtime provides one.If the function throws, the SDK records the error and rethrows the original exception — your existing error handling is not affected.

Use the same runId for every step in a single request, job, or webhook. The typed client also autocompletes valid string literals, so failpath.run("checkout", ...) and run.step("validate-cart", ...) work when those keys exist in .failpath/flows.json.

Publish your flow

Push your local flow graph to the Failpath dashboard:

npx failpath publish

Before sending anything, publish validates .failpath/flows.json, regenerates .failpath/sdk.ts, and reports any structural errors. Once validation passes, your flow definition is live on the dashboard and ready to receive events from your instrumented functions.

The .env file created by init is enough for local development, but you also need to set FAILPATH_PROJECT_KEY in your deployment environment. Platforms such as Vercel, Railway, and Convex each have their own environment variable configuration — add FAILPATH_PROJECT_KEY there so your deployed backend can send events to Failpath.

Get Started

Core Concepts

CLI

SDK

Guides

Failpath Quickstart: Instrument and Publish Your First Flow