|
| 1 | +--- |
| 2 | +title: Multiple SDK clients |
| 3 | +sidebarTitle: Multiple SDK clients |
| 4 | +description: Use TriggerClient to talk to multiple Trigger.dev projects, environments, or preview branches from a single process. |
| 5 | +--- |
| 6 | + |
| 7 | +The global `configure()` API binds the SDK to one set of credentials per process. When a single process needs to talk to more than one Trigger.dev project, environment, or preview branch, use `new TriggerClient({...})` for each target instead. Each instance owns its own auth, baseURL, and preview branch, and concurrent calls across instances stay isolated. |
| 8 | + |
| 9 | +```ts |
| 10 | +import { TriggerClient } from "@trigger.dev/sdk"; |
| 11 | + |
| 12 | +const prod = new TriggerClient({ accessToken: process.env.TRIGGER_PROD_KEY }); |
| 13 | +const preview = new TriggerClient({ |
| 14 | + accessToken: process.env.TRIGGER_PREVIEW_KEY, |
| 15 | + previewBranch: "signup-flow", |
| 16 | +}); |
| 17 | + |
| 18 | +const payload = { to: "user@example.com" }; |
| 19 | +await prod.tasks.trigger("send-email", payload); |
| 20 | +await preview.runs.list({ status: ["COMPLETED"] }); |
| 21 | +``` |
| 22 | + |
| 23 | +## Configuration |
| 24 | + |
| 25 | +`TriggerClient` accepts the same fields as `configure()`: |
| 26 | + |
| 27 | +| Field | Description | Env-var fallback | |
| 28 | +| --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | |
| 29 | +| `accessToken` | Secret key (`tr_dev_*`, `tr_prod_*`, `tr_preview_*`) or personal access token (`tr_pat_*`). | `TRIGGER_SECRET_KEY`, then `TRIGGER_ACCESS_TOKEN` | |
| 30 | +| `previewBranch` | Preview branch name when using a `tr_preview_*` key. | `TRIGGER_PREVIEW_BRANCH`, then `VERCEL_GIT_COMMIT_REF` | |
| 31 | +| `baseURL` | Override the Trigger.dev API URL. Defaults to `https://api.trigger.dev`. | `TRIGGER_API_URL` | |
| 32 | +| `requestOptions`| Request-level options (retry policy, additional headers, etc.) — see the `ApiRequestOptions` type. | — | |
| 33 | + |
| 34 | +Fields not passed to the constructor fall back to the matching env var (and then to a sensible default for `baseURL`). Explicit constructor values always win, so you can mix env-var-backed clients and fully explicit clients in the same process. |
| 35 | + |
| 36 | +```ts |
| 37 | +// Picks up TRIGGER_SECRET_KEY / TRIGGER_PREVIEW_BRANCH from env. |
| 38 | +const fromEnv = new TriggerClient(); |
| 39 | + |
| 40 | +// Explicit values override env entirely. |
| 41 | +const explicit = new TriggerClient({ |
| 42 | + accessToken: process.env.OTHER_PROJECT_KEY, |
| 43 | + previewBranch: "feature-x", |
| 44 | +}); |
| 45 | +``` |
| 46 | + |
| 47 | +If no `accessToken` resolves from either the constructor or env vars, the first API call throws an `ApiClientMissingError` with a clear message. |
| 48 | + |
| 49 | +## What's on a TriggerClient instance |
| 50 | + |
| 51 | +Each instance exposes the management surface as namespaced properties: `tasks`, `runs`, `batch`, `schedules`, `envvars`, `queues`, `deployments`, `prompts`, and `auth`. |
| 52 | + |
| 53 | +```ts |
| 54 | +import type { emailTask } from "./trigger/email"; |
| 55 | + |
| 56 | +const client = new TriggerClient(); |
| 57 | + |
| 58 | +await client.tasks.trigger<typeof emailTask>("send-email", { to: "user@example.com" }); |
| 59 | +await client.runs.list({ status: ["COMPLETED"], limit: 10 }); |
| 60 | +await client.schedules.create({ task: "daily-report", cron: "0 9 * * *" }); |
| 61 | +await client.envvars.update("proj_1234", "preview", "DATABASE_URL", { value: "..." }); |
| 62 | +``` |
| 63 | + |
| 64 | +Methods that only make sense inside a running task are not on the instance surface: `tasks.triggerAndWait`, `tasks.batchTriggerAndWait`, `tasks.triggerAndSubscribe`, `batch.triggerAndWait`, `batch.triggerByTaskAndWait`, and the task-definition helpers (`schedules.task`, `prompts.define`). |
| 65 | + |
| 66 | +## Isolation contract |
| 67 | + |
| 68 | +When you make a call through a `TriggerClient` instance, the SDK does not look at the process-wide global config, env vars (other than the constructor-time fallback), or the ambient task context. Two instances pointing at different projects can run in the same process — including in parallel under `Promise.all` — without interfering with each other. |
| 69 | + |
| 70 | +That isolation also means a call from inside a task does not automatically inherit the surrounding task's `parentRunId`, `lockToVersion`, or test flag. If you specifically want a call to inherit those (rare — usually you want a clean external trigger), opt in with `inheritContext: true`: |
| 71 | + |
| 72 | +```ts |
| 73 | +const sameProject = new TriggerClient({ |
| 74 | + accessToken: process.env.TRIGGER_SECRET_KEY, |
| 75 | + inheritContext: true, |
| 76 | +}); |
| 77 | +``` |
| 78 | + |
| 79 | +## When to use what |
| 80 | + |
| 81 | +| Scenario | Recommended | |
| 82 | +| ------------------------------------------------------------------------- | ------------------------------------ | |
| 83 | +| Single process, single project/env | `configure()` (or env vars only) | |
| 84 | +| Single process talking to multiple projects, envs, or branches | `new TriggerClient({...})` per target | |
| 85 | +| Short, sequential override (e.g. one batch under a different token) | `auth.withAuth(config, fn)` | |
| 86 | +| Inside a task, trigger a run in a different project | `new TriggerClient({...})` | |
| 87 | + |
| 88 | +See [Authentication](/management/authentication) for the underlying token types and the `auth.withAuth` helper. |
0 commit comments