The trigger.config.ts file

This file is used to configure your project and how it’s built.

The trigger.config.ts file is used to configure your Trigger.dev project. It is a TypeScript file at the root of your project that exports a default configuration object. Here’s an example:

trigger.config.ts

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

export default defineConfig({
  // Your project ref (you can see it on the Project settings page in the dashboard)
  project: "<project ref>",
  //The paths for your trigger folders
  dirs: ["./trigger"],
  retries: {
    //If you want to retry a task in dev mode (when using the CLI)
    enabledInDev: false,
    //the default retry settings. Used if you don't specify on a task.
    default: {
      maxAttempts: 3,
      minTimeoutInMs: 1000,
      maxTimeoutInMs: 10000,
      factor: 2,
      randomize: true,
    },
  },
});

The config file handles a lot of things, like:

• Specifying where your trigger tasks are located using the dirs option.
• Setting the default retry settings.
• Configuring OpenTelemetry instrumentations.
• Customizing the build process.
• Adding global task lifecycle functions.

The config file is bundled with your project, so code imported in the config file is also bundled, which can have an effect on build times and cold start duration. One important qualification is anything defined in the build config is automatically stripped out of the config file, and imports used inside build config with be tree-shaken out.

Dirs

You can specify the directories where your tasks are located using the dirs option:

trigger.config.ts

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

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

If you omit the dirs option, we will automatically detect directories that are named trigger in your project, but we recommend specifying the directories explicitly. The dirs option is an array of strings, so you can specify multiple directories if you have tasks in multiple locations.

We will search for TypeScript and JavaScript files in the specified directories and include them in the build process. We automatically exclude files that have .test or .spec in the name, but you can customize this by specifying glob patterns in the ignorePatterns option:

trigger.config.ts

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

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

Lifecycle functions

You can add lifecycle functions to get notified when any task starts, succeeds, or fails using onStart, onSuccess and onFailure:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  onSuccess: async (payload, output, { ctx }) => {
    console.log("Task succeeded", ctx.task.id);
  },
  onFailure: async (payload, error, { ctx }) => {
    console.log("Task failed", ctx.task.id);
  },
  onStart: async (payload, { ctx }) => {
    console.log("Task started", ctx.task.id);
  },
  init: async (payload, { ctx }) => {
    console.log("I run before any task is run");
  },
});

Read more about task lifecycle functions in the tasks overview.

Instrumentations

We use OpenTelemetry (OTEL) for our run logs. This means you get a lot of information about your tasks with no effort. But you probably want to add more information to your logs. For example, here’s all the Prisma calls automatically logged:

Here we add Prisma and OpenAI instrumentations to your trigger.config.ts file.

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  telemetry: {
    instrumentations: [new PrismaInstrumentation(), new OpenAIInstrumentation()],
  },
});

There is a huge library of instrumentations you can easily add to your project like this.

Some ones we recommend:

Package	Description
@opentelemetry/instrumentation-http	Logs all HTTP calls
@prisma/instrumentation	Logs all Prisma calls, you need to enable tracing
@traceloop/instrumentation-openai	Logs all OpenAI calls

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

Telemetry Exporters

You can also configure custom telemetry exporters to send your traces and logs to other external services. For example, you can send your logs to Axiom. First, add the opentelemetry exporter packages to your package.json file:

package.json

"dependencies": {
  "@opentelemetry/exporter-logs-otlp-http": "0.52.1",
  "@opentelemetry/exporter-trace-otlp-http": "0.52.1"
}

Then, configure the exporters in your trigger.config.ts file:

trigger.config.ts

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

// Initialize OTLP trace exporter with the endpoint URL and headers;
export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  telemetry: {
    instrumentations: [
      // Your instrumentations here
    ],
    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,
        },
      }),
    ],
  },
});

Make sure to set the AXIOM_API_TOKEN and AXIOM_DATASET environment variables in your project.

The logExporters option is available in the v4 beta SDK. See our v4 upgrade guide for more information.

It’s important to note that you cannot configure exporters using OTEL_* environment variables, as they would conflict with our internal telemetry. Instead you should configure the exporters via passing in arguments to the OTLPTraceExporter and OTLPLogExporter constructors. For example, here is how you can configure exporting to Honeycomb:

trigger.config.ts

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

// Initialize OTLP trace exporter with the endpoint URL and headers;
export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  telemetry: {
    instrumentations: [
      // Your instrumentations here
    ],
    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,
        },
      }),
    ],
  },
});

Runtime

We currently only officially support the node runtime, but you can try our experimental bun runtime by setting the runtime option in your config file:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  runtime: "bun",
});

See our Bun guide for more information.

Node.js versions

Trigger.dev runs your tasks on specific Node.js versions:

• v3: Uses Node.js 21.7.3
• v4: Uses Node.js 21.7.3

Default machine

You can specify the default machine for all tasks in your project:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  defaultMachine: "large-1x",
});

See our machines documentation for more information.

Log level

You can set the log level for your project:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  logLevel: "debug",
});

The logLevel only determines which logs are sent to the Trigger.dev instance when using the logger API. All console based logs are always sent.

Max duration

You can set the default maxDuration for all tasks in your project:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  maxDuration: 60, // 60 seconds
});

See our maxDuration guide for more information.

Build configuration

You can customize the build process using the build option:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    // Don't bundle these packages
    external: ["header-generator"],
  },
});

The trigger.config.ts file is included in the bundle, but with the build configuration stripped out. These means any imports only used inside the build configuration are also removed from the final bundle.

External

All code is bundled by default, but you can exclude some packages from the bundle using the external option:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    external: ["header-generator"],
  },
});

When a package is excluded from the bundle, it will be added to a dynamically generated package.json file in the build directory. The version of the package will be the same as the version found in your node_modules directory.

Each entry in the external should be a package name, not necessarily the import path. For example, if you want to exclude the ai package, but you are importing ai/rsc, you should just include ai in the external array:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    external: ["ai"],
  },
});

Any packages that install or build a native binary should be added to external, as native binaries cannot be bundled. For example, re2, sharp, and sqlite3 should be added to external.

JSX

You can customize the jsx options that are passed to esbuild using the jsx option:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    jsx: {
      // Use the Fragment component instead of React.Fragment
      fragment: "Fragment",
      // Use the h function instead of React.createElement
      factory: "h",
      // Turn off automatic runtime
      automatic: false,
    },
  },
});

By default we enabled esbuild’s automatic JSX runtime which means you don’t need to import React in your JSX files. You can disable this by setting automatic to false.

See the esbuild JSX documentation for more information.

Conditions

You can add custom import conditions to your build using the conditions option:

trigger.config.ts

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

export default defineConfig({
  project: "<project ref>",
  // Your other config settings...
  build: {
    conditions: ["react-server"],
  },
});

These conditions effect how imports are resolved during the build process. For example, the react-server condition will resolve ai/rsc to the server version of the ai/rsc export.

Custom conditions will also be passed to the node runtime when running your tasks.

Extensions

Build extension allow you to hook into the build system and customize the build process or the resulting bundle and container image (in the case of deploying). You can use pre-built extensions by installing the @trigger.dev/build package into your devDependencies, or you can create your own.

additionalFiles

See the additionalFiles documentation for more information.

additionalPackages

See the additionalPackages documentation for more information.

emitDecoratorMetadata

See the emitDecoratorMetadata documentation for more information.

Prisma

See the prismaExtension documentation for more information.

syncEnvVars

See the syncEnvVars documentation for more information.

puppeteer

See the puppeteer documentation for more information.

ffmpeg

See the ffmpeg documentation for more information.

esbuild plugins

See the esbuild plugins documentation for more information.

aptGet

See the aptGet documentation for more information.