The trigger.config.ts file

The trigger.config.ts file lives at the root of your project and is the single source of truth for how your Trigger.dev project is configured and built. It exports a default configuration object created with defineConfig.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  // Your project ref — find it on the Project settings page in the dashboard
  project: "<project ref>",
  // Paths to directories containing your trigger tasks
  dirs: ["./trigger"],
  retries: {
    // Enable retries during local dev (CLI)
    enabledInDev: false,
    // Default retry policy applied to all tasks unless overridden
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },
});

The config file handles:

Specifying where your trigger tasks are located via the dirs option
Setting default retry policies
Configuring OpenTelemetry instrumentations and exporters
Customizing the build process and bundle
Adding global task lifecycle hooks

The config file is bundled with your project, so anything imported at the top level also ends up in the bundle — which can affect build times and cold start duration. Anything defined inside the build config is automatically stripped from the final bundle, and imports only used there are tree-shaken out.

`project`

Required. Your project reference, which you can find on the Project settings page in the Trigger.dev dashboard.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "proj_abcdefgh1234",
});

`dirs`

An array of directory paths where your task files are located. Trigger.dev scans these directories for TypeScript and JavaScript files and includes them in the build.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  dirs: ["./trigger"],
});

If you omit dirs, Trigger.dev will automatically detect directories named trigger in your project, but explicitly specifying them is recommended. You can pass multiple directories:

trigger.config.ts

export default defineConfig({
  project: "<project ref>",
  dirs: ["./trigger", "./jobs", "./src/background"],
});

Files with .test or .spec in their name are excluded automatically. Use ignorePatterns to add your own exclusion rules:

trigger.config.ts

export default defineConfig({
  project: "<project ref>",
  dirs: ["./trigger"],
  ignorePatterns: ["**/*.my-test.ts"],
});

`tsconfig`

A custom path to a tsconfig.json file. Useful when your project uses a non-standard tsconfig location.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  dirs: ["./trigger"],
  tsconfig: "./tsconfig.trigger.json",
});

`retries`

Configures the default retry behavior for all tasks in the project. Individual tasks can override these settings.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  retries: {
    // Whether to retry failed tasks when running in dev mode
    enabledInDev: false,
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,       // Exponential backoff multiplier
      randomize: true, // Add jitter to retry delays
    },
  },
});

`maxDuration`

Sets the default maximum duration (in seconds) for all tasks. Tasks that exceed this duration will be killed. Individual tasks can override this value.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  maxDuration: 300, // 5 minutes
});

Configure maxDuration per task or globally to control how long a task can run before it times out.

`defaultMachine`

The default machine preset to use for all tasks. Individual tasks can override this.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  defaultMachine: "small-2x",
});

See the machines documentation for available presets.

`runtime`

The runtime to use when executing tasks. Defaults to node. An experimental bun runtime is also available.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  runtime: "bun",
});

The bun runtime uses Bun instead of Node.js to execute your tasks. See the Bun documentation for more about Bun compatibility.

`logLevel`

Controls which log levels are forwarded to Trigger.dev when using the logger API. All console.* calls are always forwarded regardless of this setting.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  logLevel: "debug", // "log" | "error" | "warn" | "info" | "debug" | "trace"
});

`enableConsoleLogging` / `disableConsoleInterceptor`

Control console logging behavior in development:

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  // Print console logs to stdout while running the dev CLI
  enableConsoleLogging: true,
  // Prevent console logs from being sent to the Trigger.dev dashboard
  disableConsoleInterceptor: false,
});

`processKeepAlive`

Keeps the worker process alive between task executions so subsequent tasks skip process startup time. The process may still be killed at any time — no guarantees are made about process lifetime.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  // Simple boolean to enable with defaults
  processKeepAlive: true,
});

Or pass an object for granular control:

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  processKeepAlive: {
    enabled: true,
    // Kill the process after this many executions
    maxExecutionsPerProcess: 50,
    // Maximum number of concurrent processes kept alive in dev
    devMaxPoolSize: 25,
  },
});

`extraCACerts`

Path to a CA certificate file that will be added to NODE_EXTRA_CA_CERTS. Useful when running against a self-hosted Trigger.dev instance with a self-signed certificate. The path must start with ./ and be relative to the project root.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  extraCACerts: "./certs/ca.crt",
});

`legacyDevProcessCwdBehaviour`

Controls how the working directory is set in development. When false, the working directory is set to the build directory, matching production behavior more closely.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  legacyDevProcessCwdBehaviour: false, // Defaults to true
});

Lifecycle functions

Global lifecycle hooks that run for every task in the project. Use these for cross-cutting concerns like notifications, observability, or shared setup.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  // Runs before any task executes — useful for global setup
  init: async ({ payload, ctx }) => {
    console.log("Initializing task", ctx.task.id);
  },
  // Called when any task run starts
  onStart: async ({ payload, ctx }) => {
    console.log("Task started", ctx.task.id);
  },
  // Called when any task run completes successfully
  onSuccess: async ({ payload, output, ctx }) => {
    console.log("Task succeeded", ctx.task.id);
  },
  // Called when any task run fails after all retries are exhausted
  onFailure: async ({ payload, error, ctx }) => {
    console.error("Task failed", ctx.task.id, error);
  },
});

See the tasks overview for more on lifecycle hooks.

`telemetry`

Trigger.dev uses OpenTelemetry (OTEL) for run logs. You can add instrumentations to automatically trace calls to libraries like Prisma, OpenAI, and more.

Instrumentations

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";
import { PrismaInstrumentation } from "@prisma/instrumentation";
import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";

export default defineConfig({
  project: "<project ref>",
  telemetry: {
    instrumentations: [
      new PrismaInstrumentation(),
      new OpenAIInstrumentation(),
    ],
  },
});

Recommended instrumentations:

Package	Description
`@opentelemetry/instrumentation-http`	Logs all HTTP calls
`@prisma/instrumentation`	Logs all Prisma calls (requires tracing enabled)
`@traceloop/instrumentation-openai`	Logs all OpenAI calls

@opentelemetry/instrumentation-fs which logs all file system calls is currently not supported.

Telemetry exporters

You can export traces, logs, and metrics to external observability services. Do not use OTEL_* environment variables — configure exporters directly in the constructor to avoid conflicts with Trigger.dev’s internal telemetry.

import { defineConfig } from "@trigger.dev/sdk";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";

export default defineConfig({
  project: "<project ref>",
  telemetry: {
    instrumentations: [],
    logExporters: [
      new OTLPLogExporter({
        url: "https://api.axiom.co/v1/logs",
        headers: {
          Authorization: `Bearer ${process.env.AXIOM_API_TOKEN}`,
          "X-Axiom-Dataset": process.env.AXIOM_DATASET,
        },
      }),
    ],
    exporters: [
      new OTLPTraceExporter({
        url: "https://api.axiom.co/v1/traces",
        headers: {
          Authorization: `Bearer ${process.env.AXIOM_API_TOKEN}`,
          "X-Axiom-Dataset": process.env.AXIOM_DATASET,
        },
      }),
    ],
    metricExporters: [
      new OTLPMetricExporter({
        url: "https://api.axiom.co/v1/metrics",
        headers: {
          Authorization: `Bearer ${process.env.AXIOM_API_TOKEN}`,
          "x-axiom-metrics-dataset": process.env.AXIOM_METRICS_DATASET,
        },
      }),
    ],
  },
});

import { defineConfig } from "@trigger.dev/sdk";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";

export default defineConfig({
  project: "<project ref>",
  telemetry: {
    instrumentations: [],
    logExporters: [
      new OTLPLogExporter({
        url: "https://api.honeycomb.io/v1/logs",
        headers: {
          "x-honeycomb-team": process.env.HONEYCOMB_API_KEY,
          "x-honeycomb-dataset": process.env.HONEYCOMB_DATASET,
        },
      }),
    ],
    exporters: [
      new OTLPTraceExporter({
        url: "https://api.honeycomb.io/v1/traces",
        headers: {
          "x-honeycomb-team": process.env.HONEYCOMB_API_KEY,
          "x-honeycomb-dataset": process.env.HONEYCOMB_DATASET,
        },
      }),
    ],
    metricExporters: [
      new OTLPMetricExporter({
        url: "https://api.honeycomb.io/v1/metrics",
        headers: {
          "x-honeycomb-team": process.env.HONEYCOMB_API_KEY,
          "x-honeycomb-dataset": process.env.HONEYCOMB_DATASET,
        },
      }),
    ],
  },
});

Axiom’s /v1/metrics endpoint only supports protobuf. Use @opentelemetry/exporter-metrics-otlp-proto instead of @opentelemetry/exporter-metrics-otlp-http for metrics when using Axiom. Axiom also requires a separate, dedicated dataset for metrics.

`build`

Customizes the esbuild-based build pipeline that packages your tasks for deployment.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  build: {
    // Packages to exclude from the bundle
    external: ["sharp", "re2"],
    // Automatically detect and externalize native packages (default: true)
    autoDetectExternal: true,
    // Preserve function/class names in the bundle (default: true)
    keepNames: true,
    // Minify the generated bundle (default: false, experimental)
    minify: false,
  },
});

The build configuration is stripped from the final bundle. Imports only used inside the build config are also tree-shaken out, so they do not affect bundle size or cold start time.

`build.external`

All code is bundled by default. Use external to exclude packages — they will instead be listed in a dynamically generated package.json and installed at runtime. Specify package names, not import paths. For example, to exclude ai/rsc use "ai" not "ai/rsc":

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  build: {
    external: ["ai"],
  },
});

Packages that include native binaries (.node files) or use WebAssembly (WASM) must be added to external. Examples include re2, sharp, sqlite3, and any WASM packages. Attempting to bundle them will result in a build error.

`build.jsx`

Customize the JSX transform options passed to esbuild. By default, esbuild’s automatic JSX runtime is enabled, so you do not need to import React in JSX files.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  build: {
    jsx: {
      factory: "h",
      fragment: "Fragment",
      automatic: false, // Disable automatic JSX runtime
    },
  },
});

`build.conditions`

Add custom import conditions that affect how imports are resolved during the build. These conditions are also passed to the Node.js runtime.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";

export default defineConfig({
  project: "<project ref>",
  build: {
    // Resolves "ai/rsc" to the server version of the export
    conditions: ["react-server"],
  },
});

`build.extensions`

Build extensions hook into the build pipeline to customize how your project is built or what gets included in the container image. You can use the built-in extensions from @trigger.dev/build or write your own.

trigger.config.ts

import { defineConfig } from "@trigger.dev/sdk";
import { ffmpeg } from "@trigger.dev/build/extensions/core";
import { prismaExtension } from "@trigger.dev/build/extensions/prisma";

export default defineConfig({
  project: "<project ref>",
  build: {
    extensions: [
      ffmpeg(),
      prismaExtension({
        schema: "prisma/schema.prisma",
      }),
    ],
  },
});

See Build extensions overview for the full list of available extensions.

Getting Started

Writing Tasks

AI Agents & Realtime

Configuration & Deployment

Observability & Management

Self-hosting

The trigger.config.ts file

`project`

`dirs`

`tsconfig`

`retries`

`maxDuration`

`defaultMachine`

`runtime`

`logLevel`

`enableConsoleLogging` / `disableConsoleInterceptor`

`processKeepAlive`

`extraCACerts`

`legacyDevProcessCwdBehaviour`

Lifecycle functions

`telemetry`

Instrumentations

Telemetry exporters

`build`

`build.external`

`build.jsx`

`build.conditions`

`build.extensions`

​project

​dirs

​tsconfig

​retries

​maxDuration

​defaultMachine

​runtime

​logLevel

​enableConsoleLogging / disableConsoleInterceptor

​processKeepAlive

​extraCACerts

​legacyDevProcessCwdBehaviour

​Lifecycle functions

​telemetry

​Instrumentations

​Telemetry exporters

​build

​build.external

​build.jsx

​build.conditions

​build.extensions

`project`

`dirs`

`tsconfig`

`retries`

`maxDuration`

`defaultMachine`

`runtime`

`logLevel`

`enableConsoleLogging` / `disableConsoleInterceptor`

`processKeepAlive`

`extraCACerts`

`legacyDevProcessCwdBehaviour`

Lifecycle functions

`telemetry`

Instrumentations

Telemetry exporters

`build`

`build.external`

`build.jsx`

`build.conditions`

`build.extensions`