Skip to main content

​
Initializing the client

Use the static HatchetClient.init() factory method to create a client instance. It reads configuration from environment variables automatically:
hatchet-client.ts
import { HatchetClient } from '@hatchet-dev/typescript-sdk';

export const hatchet = HatchetClient.init();
You can also pass a partial ClientConfig object to override specific settings: 
import { HatchetClient } from '@hatchet-dev/typescript-sdk';

export const hatchet = HatchetClient.init({
  token: 'ey...',
  host_port: 'localhost:7070',
  namespace: 'my-app',
  log_level: 'INFO',
});

​
Signature

HatchetClient.init<T extends Record<string, any> = {}, U extends Record<string, any> = {}>(config?: Partial<ClientConfig>, options?: HatchetClientOptions, axiosConfig?: AxiosRequestConfig): HatchetClient<T, U>
​
config
Partial<ClientConfig>
Optional configuration overrides. All fields are optional — any value not provided is read from the corresponding environment variable.
​
options
HatchetClientOptions
Optional SDK-level options such as config_path (path to a YAML config file) and credentials (custom gRPC channel credentials).
​
axiosConfig
AxiosRequestConfig
Optional Axios configuration applied to all REST API calls made by the client.

​
ClientConfig fields

​
token
string
required
Your Hatchet API token (a JWT). Required — the client throws an error if it is not set.
​
host_port
string
default:"Read from token"
The gRPC server address, e.g. "localhost:7070". When not set, the value is read from the token’s embedded address.
​
api_url
string
default:"Read from token"
The base URL for REST API calls. When not set, derived from the token.
​
namespace
string
default:"\"\""
A namespace prefix applied to all workflow names and event keys. Set via HATCHET_CLIENT_NAMESPACE.
​
tenant_id
string
default:"Read from token"
The tenant ID. Extracted from the JWT automatically when not explicitly set.
​
log_level
'OFF' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'
Log level for the SDK’s internal logger.
​
tls_config
ClientTLSConfig
TLS settings. Key sub-fields:
  • tls_strategy — "tls" (default), "mtls", or "none"
  • cert_file, key_file, ca_file — paths to certificate files
  • server_name — override the TLS server name
​
otel
OpenTelemetryConfig
OpenTelemetry configuration. Sub-fields:
  • excludedAttributes — list of span attribute keys to omit
  • includeTaskNameInSpanName — include the task name in the span name
​
cancellation_grace_period
number
default:"1000"
Grace period in milliseconds given to a task after cancellation before the SDK forcibly aborts it.

​
Feature clients

All feature clients are exposed as lazy-initialized properties on the HatchetClient instance. Each client wraps a specific area of the Hatchet API.
PropertyTypeDescription
hatchet.runsRunsClientList, get, cancel, and replay task and workflow runs.
hatchet.cronsCronClientCreate and manage cron workflow triggers.
hatchet.scheduledScheduleClientCreate and manage one-off scheduled workflow runs.
hatchet.eventsEventClientPush events that trigger event-based workflows.
hatchet.workersWorkersClientList, get, pause, and unpause workers.
hatchet.workflowsWorkflowsClientList and get workflow declarations.
hatchet.logsLogsClientAccess run log lines.
hatchet.metricsMetricsClientRead task status metrics.
hatchet.ratelimitsRatelimitsClientManage rate limit configurations.
hatchet.webhooksWebhooksClientCreate and manage incoming webhook endpoints.
hatchet.filtersFiltersClientCreate and manage workflow run filters.
hatchet.tenantTenantClientManage tenant settings.
hatchet.celCELClientEvaluate CEL expressions.

​
Namespacing

When namespace is set, the SDK automatically prefixes workflow names and event keys with the namespace value. This lets multiple environments (e.g. dev, staging, prod) share the same Hatchet tenant without name collisions. 
import { HatchetClient } from '@hatchet-dev/typescript-sdk';

const hatchet = HatchetClient.init({
  namespace: 'my-app',
});

// Workflow names and event keys are automatically prefixed with "my-app"
const task = hatchet.task({
  name: 'process',
  fn: async (input) => { /* ... */ },
});
// Registered internally as "my-app:process"
You can also set the namespace via the HATCHET_CLIENT_NAMESPACE environment variable.

​
Middleware

Attach typed before/after hooks to every task on this client using .withMiddleware(): 
import { HatchetClient } from '@hatchet-dev/typescript-sdk';

const hatchet = HatchetClient.init().withMiddleware({
  before: async (input, ctx) => {
    // Return extra fields to merge into input
    return { requestId: crypto.randomUUID() };
  },
  after: async (output, ctx, input) => {
    // Return extra fields to merge into output, or void to pass through
  },
});
The return types of before and after hooks are inferred and surfaced in all task function signatures created from this client.

Build docs developers (and LLMs) love

Get started for freeTalk to us