Project setup

1. Clone or copy the source/ directory into your project root (e.g., ./hatchet-source/).
2. Start the Hatchet server locally using Docker Compose:

   cd hatchet-source
   docker compose up -d
   

3. Obtain your API token from the Hatchet dashboard (default: http://localhost:8080) under Settings > API Tokens.
4. Set environment variables in your project's .env:

   HATCHET_CLIENT_TOKEN=<your-api-token>
   HATCHET_CLIENT_HOST_PORT=localhost:7077
   

5. Install the TypeScript SDK:

   npm install @hatchet-dev/typescript-sdk dotenv
   

6. Import and initialize the client in your application entry point:

   import Hatchet from '@hatchet-dev/typescript-sdk';
   const hatchet = Hatchet.init();
   

7. For tsconfig.json, ensure "moduleResolution": "bundler" or "node16" and "esModuleInterop": true.

Public API

useNotifications

import { useNotifications } from '@/hooks/notifications';

function useNotifications(): {
  notifications: Notification[];
  isLoading: boolean;
}

Aggregates resource limit alerts, invite notifications, and onboarding prompts into a single sorted list. Use this hook in any top-level layout component that needs to surface system-level alerts to the user. The returned array is sorted descending by timestamp.

filterSpanTrees

import { filterSpanTrees, FilteredSpanTree } from
  '@/components/v1/cloud/observability/trace-search';

function filterSpanTrees(trees: SpanTree[], query: ParsedTraceQuery): FilteredSpanTree[];

Filters a set of distributed trace span trees against a structured query produced by parseTraceQuery. Use this when rendering trace search results in the observability dashboard to narrow down spans by status, duration, or service name without a server round-trip.

parseTraceQuery

import { parseTraceQuery, ParsedTraceQuery } from
  '@/components/v1/cloud/observability/trace-search';

function parseTraceQuery(input: string): ParsedTraceQuery;

Parses a free-text trace search string into a structured ParsedTraceQuery object. Feed the result directly into filterSpanTrees or use it to construct API query parameters. Use this when building custom trace search UIs on top of Hatchet's observability layer.

queries (API query factory)

import { queries } from '@/lib/api';

// queries is an object of TanStack Query queryKey/queryFn factories
// e.g.: queries.workflows.list(tenantId)

The queries export from frontend/app/src/lib/api provides pre-built TanStack Query descriptors for every Hatchet REST endpoint. Pass these directly to useQuery or useSuspenseQuery to fetch workflows, runs, workers, and tenant data with correct cache keys and typing.

Working examples

Scenario - Define and run a background task

Register a simple task and trigger it from an Express route. The Hatchet worker picks it up durably, retrying on failure.

import Hatchet, { Context } from '@hatchet-dev/typescript-sdk';
import 'dotenv/config';

const hatchet = Hatchet.init();

// Define the workflow
const emailWorkflow = hatchet.workflow({
  name: 'send-email',
  steps: [
    {
      name: 'send',
      run: async (ctx: Context) => {
        const { to, subject } = ctx.workflowInput();
        console.log(`Sending email to ${to}: ${subject}`);
        // your SMTP logic here
        return { sent: true };
      },
    },
  ],
});

// Start the worker (runs in a separate process or file)
async function startWorker() {
  const worker = await hatchet.worker('email-worker');
  await worker.registerWorkflow(emailWorkflow);
  worker.start();
}

// Trigger the task from your API layer
async function triggerEmail(to: string, subject: string) {
  await hatchet.admin.runWorkflow('send-email', { to, subject });
}

startWorker().catch(console.error);

Scenario - Query workflow runs using the frontend API client

Use the generated API client and TanStack Query inside a React component to list recent workflow runs for a tenant.

import { useQuery } from '@tanstack/react-query';
import { queries } from '@/lib/api';

interface Props {
  tenantId: string;
}

export function WorkflowRunList({ tenantId }: Props) {
  const { data, isLoading } = useQuery({
    ...queries.workflowRuns.list(tenantId, { limit: 20 }),
  });

  if (isLoading) return <p>Loading...</p>;

  return (
    <ul>
      {data?.rows?.map((run) => (
        <li key={run.metadata.id}>
          {run.displayName} — {run.status}
        </li>
      ))}
    </ul>
  );
}

Scenario - Render a trace search input with autocomplete

Embed Hatchet's trace search UI into a custom observability page, wiring the query parser and span filter together.

import { useState } from 'react';
import {
  TraceSearchInput,
  parseTraceQuery,
  filterSpanTrees,
} from '@/components/v1/cloud/observability/trace-search';
import type { FilteredSpanTree } from '@/components/v1/cloud/observability/trace-search';

interface Props {
  spanTrees: any[];
}

export function CustomTraceSearch({ spanTrees }: Props) {
  const [results, setResults] = useState<FilteredSpanTree[]>([]);

  const handleSearch = (rawQuery: string) => {
    const parsed = parseTraceQuery(rawQuery);
    const filtered = filterSpanTrees(spanTrees, parsed);
    setResults(filtered);
  };

  return (
    <div>
      <TraceSearchInput onSearch={handleSearch} />
      <pre>{JSON.stringify(results, null, 2)}</pre>
    </div>
  );
}

File walkthrough

• .claude/ - Contains SKILL.md prompts that teach AI assistants how to scaffold new TUI views in the Hatchet dashboard.
• .github/ - GitHub Actions workflows for Go/TS/Python SDK CI, release automation, lint, E2E tests, and OSV security scanning.
• api/ - Go HTTP server wiring: route registration, authn (session/cookie), authz (RBAC via Casbin YAML), and request handlers per resource type.
• api-contracts/ - Source-of-truth OpenAPI and protobuf definitions; drives code generation for all SDK clients.
• assets/ - SVG logos and marketing images referenced in the README and dashboard.
• cmd/ - main.go entry points for hatchet-engine, hatchet-api, and hatchet CLI binary.
• contributing/ - Local dev setup, architecture overview, and PR conventions for open-source contributors.
• examples/ - Self-contained runnable examples demonstrating common patterns (fan-out, DAGs, cron, durable sleep).
• frontend/ - Vite + React 18 dashboard: TanStack Router for routing, TanStack Query for data fetching, Tailwind for styling.
• hack/ - Shell and Go scripts for schema migration, protobuf codegen, and seeding local dev data.
• internal/ - Core engine logic: scheduler, dispatcher, event ingestion, ticker, repository layer (sqlc-generated), and gRPC services.
• pkg/ - The public-facing Go client and worker SDK imported by user applications.
• sdks/ - First-party client SDKs for TypeScript, Python, and Ruby with their own build/publish pipelines.
• sql/ - SQLC query files and numbered Postgres migration files; the authoritative schema source.
• docker-compose.yml - Composes all Hatchet services (Postgres, engine, API, frontend, RabbitMQ) for local development.
• Taskfile.yaml - Unified task runner: task generate, task migrate, task test, etc.

Common pitfalls and fixes

• Missing HATCHET_CLIENT_TOKEN: The SDK throws at init time if the token env var is absent. Always load .env before importing the SDK (import 'dotenv/config' as the first line).
• gRPC port vs HTTP port confusion: The worker connects on HATCHET_CLIENT_HOST_PORT (default 7077, gRPC), not the dashboard HTTP port (8080). Set them independently.
• ESM/CJS interop: The TypeScript SDK publishes ESM. If your project uses "type": "commonjs", add "esModuleInterop": true and "allowSyntheticDefaultImports": true to tsconfig.json.
• Frontend path aliases (@/): The dashboard source uses @/ aliased to frontend/app/src/. If copying components out, configure tsconfig.json paths and your bundler (Vite: resolve.alias) to match.
• Database migrations not applied: Running docker compose up does not auto-migrate. Run task migrate or hatchet server migrate before starting the engine, or the API will return 500s on all routes.
• TanStack Query v5 breaking changes: queries descriptors use the v5 object form ({ queryKey, queryFn }). Spread them with useQuery({ ...queries.x.y() }); do not pass them as positional arguments as in v4.

Vibe-coding prompt template

I have dropped the Hatchet source repository into ./hatchet-source/ in my project.
I also have USAGE.md (the integration guide) in the same directory.

My project is a Node.js/TypeScript backend using Express and a React frontend
using TanStack Query v5.

Please help me integrate Hatchet step by step:

1. Read USAGE.md and the relevant files under hatchet-source/ to understand
   the real exported APIs (do not invent any symbols).
2. Set up the Hatchet worker process that connects to a local Hatchet server
   (docker compose up in hatchet-source/).
3. Define a background task workflow named "process-upload" that accepts
   { fileUrl: string } and logs the URL.
4. Trigger "process-upload" from my Express POST /upload route.
5. Add a React component that lists the last 10 workflow runs for my tenant,
   using the `queries` factory from hatchet-source/frontend/app/src/lib/api.
6. Wire up environment variables (HATCHET_CLIENT_TOKEN, HATCHET_CLIENT_HOST_PORT)
   using dotenv.
7. Show me the tsconfig.json changes needed for ESM interop and the @/ path alias.

Use only imports and symbols that appear in USAGE.md or the actual source files.

License and credit

Hatchet is released under the MIT License. See source/LICENSE for the full text. Upstream repository and documentation: https://github.com/hatchet-dev/hatchet. Cloud-hosted version available at https://cloud.onhatchet.run.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.