feat(sdk): replace onStart lifecycle hook with onStartAttempt #2515

ericallam · 2025-09-16T13:59:04Z

Prevent uncaught errors in the onSuccess, onComplete, and onFailure lifecycle hooks from failing attempts/runs.

Deprecated the onStart lifecycle hook (which only fires before the run function on the first attempt). Replaced with onStartAttempt that fires before the run function on every attempt:

export const taskWithOnStartAttempt = task({
  id: "task-with-on-start-attempt",
  onStartAttempt: async ({ payload, ctx }) => {
    //...
  },
  run: async (payload: any, { ctx }) => {
    //...
  },
});

// Default a global lifecycle hook using tasks
tasks.onStartAttempt(({ ctx, payload, task }) => {
  console.log(
    `Run ${ctx.run.id} started on task ${task} attempt ${ctx.run.attempt.number}`,
    ctx.run
  );
});

If you want to execute code before just the first attempt, you can use the onStartAttempt function and check ctx.run.attempt.number === 1:

export const taskWithOnStartAttempt = task({
  id: "task-with-on-start-attempt",
  onStartAttempt: async ({ payload, ctx }) => {
    if (ctx.run.attempt.number === 1) {
      console.log("Run started on attempt 1", ctx.run);
    }
  },
});

…nFailure hooks to fail attempts & in some cases runs

changeset-bot · 2025-09-16T13:59:09Z

🦋 Changeset detected

Latest commit: 494b659

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@trigger.dev/sdk	Minor
@trigger.dev/python	Minor
d3-chat	Patch
references-d3-openai-agents	Patch
references-nextjs-realtime	Patch
@trigger.dev/build	Minor
@trigger.dev/core	Minor
@trigger.dev/react-hooks	Minor
@trigger.dev/redis-worker	Minor
@trigger.dev/rsc	Minor
@trigger.dev/schema-to-json	Minor
@trigger.dev/database	Minor
@trigger.dev/otlp-importer	Minor
trigger.dev	Minor
@internal/cache	Patch
@internal/clickhouse	Patch
@internal/redis	Patch
@internal/replication	Patch
@internal/run-engine	Patch
@internal/schedule-engine	Patch
@internal/testcontainers	Patch
@internal/tracing	Patch
@internal/zod-worker	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2025-09-16T13:59:23Z

Walkthrough

Adds a new lifecycle hook onStartAttempt that runs before every task attempt; onStart remains as a deprecated-first-attempt hook. Documentation and examples updated and deprecated init/cleanup sections added. Core types, lifecycle manager, and LifecycleHooksAPI were extended to register/retrieve global and per-task start-attempt hooks. Task executor now invokes start-attempt hooks (including on initial attempt), merges global init results with task init results, and no longer propagates errors from onSuccess/onFailure/onComplete hooks. SDK and shared code expose tasks.onStartAttempt and per-task onStartAttempt; UI adds a task-hook-onStartAttempt icon mapping. Tests added for start-attempt ordering and onSuccess error non‑propagation. Minor trailing-newline change to a package.json.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The PR description describes the behavior changes and provides useful code examples for onStartAttempt, but it does not follow the repository's required template: it omits the "Closes #" line, the ✅ Checklist, a Testing section detailing validation steps and CI/test results, a short Changelog entry, and optional screenshots or migration notes; because multiple required template sections are missing the description does not meet the repository template requirements.	Please update the PR description to follow the template: add "Closes #" if applicable, complete the checklist, add a Testing section with explicit steps, test commands and CI/test results, include a short Changelog summary describing the user-visible change, and attach screenshots or migration notes if relevant so reviewers can reproduce and verify the change.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The PR title "feat(sdk): replace onStart lifecycle hook with onStartAttempt" is concise, specific, and accurately reflects the primary change in the diff (deprecating onStart and introducing onStartAttempt across the SDK, docs, and tests), so it communicates the main intent clearly to reviewers and history scanners.

✨ Finishing touches

📝 Generate Docstrings

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch ea-branch-88

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6170b3d and 494b659.

📒 Files selected for processing (1)

packages/trigger-sdk/src/v3/hooks.ts (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

packages/trigger-sdk/src/v3/hooks.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (23)

GitHub Check: units / internal / 🧪 Unit Tests: Internal (4, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (8, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (2, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (6, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (7, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (3, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (5, 8)
GitHub Check: units / internal / 🧪 Unit Tests: Internal (1, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (6, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (5, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (8, 8)
GitHub Check: e2e / 🧪 CLI v3 tests (ubuntu-latest - pnpm)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (3, 8)
GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - pnpm)
GitHub Check: e2e / 🧪 CLI v3 tests (ubuntu-latest - npm)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (2, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (7, 8)
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (1, 8)
GitHub Check: typecheck / typecheck
GitHub Check: units / webapp / 🧪 Unit Tests: Webapp (4, 8)
GitHub Check: units / packages / 🧪 Unit Tests: Packages (1, 1)
GitHub Check: e2e / 🧪 CLI v3 tests (windows-latest - npm)
GitHub Check: Analyze (javascript-typescript)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (7)

.changeset/tiny-carrots-rest.md (4)
2-3: Include all affected packages in the changeset

Core types and APIs were added; ensure @trigger.dev/core (and any other published packages touched) receive a bump in this PR’s changesets, not just @trigger.dev/sdk.

20-27: Clarify file location for global hooks

Docs should state that global lifecycle hooks belong in trigger.config.ts per established guidance.

Apply this doc tweak:
-// Default a global lifecycle hook using tasks
+// Default a global lifecycle hook using tasks (in trigger.config.ts)
 tasks.onStartAttempt(({ ctx, payload, task }) => {
31-40: Code-fence filename syntax may not render

```ts /trigger/on-start-attempt.ts might not be recognized by your MDX tooling. Prefer title= or a preceding caption.

5-5: Specify logging/telemetry behavior for swallowed errors

If onSuccess/onComplete/onFailure errors no longer fail runs, note that they’re still captured in logs/metrics.
packages/core/src/v3/lifecycle-hooks-api.ts (1)
7-39: Re-export full StartAttempt types for consistency

You currently export only AnyOnStartAttemptHookFunction. Re-export OnStartAttemptHookFunction and TaskStartAttemptHookParams like other hooks to aid typing.
 export type {
   OnInitHookFunction,
   AnyOnInitHookFunction,
   RegisteredHookFunction,
   TaskInitHookParams,
   TaskStartHookParams,
   OnStartHookFunction,
   AnyOnStartHookFunction,
+  // StartAttempt
+  OnStartAttemptHookFunction,
+  TaskStartAttemptHookParams,
   TaskFailureHookParams,
   AnyOnFailureHookFunction,
   TaskSuccessHookParams,
   AnyOnSuccessHookFunction,
   TaskCompleteHookParams,
   AnyOnCompleteHookFunction,
   TaskWaitHookParams,
   AnyOnWaitHookFunction,
   TaskResumeHookParams,
   AnyOnResumeHookFunction,
   TaskCatchErrorHookParams,
   AnyOnCatchErrorHookFunction,
   TaskCompleteResult,
   TaskMiddlewareHookParams,
   AnyOnMiddlewareHookFunction,
   OnMiddlewareHookFunction,
   OnCleanupHookFunction,
   AnyOnCleanupHookFunction,
   TaskCleanupHookParams,
   TaskWait,
   TaskCancelHookParams,
   OnCancelHookFunction,
   AnyOnCancelHookFunction,
   AnyOnStartAttemptHookFunction,
 } from "./lifecycleHooks/types.js";
packages/core/src/v3/types/tasks.ts (1)
338-349: Consider clarifying the deprecation timeline for onStart.

While the deprecation notice directs users to onStartAttempt, consider adding information about when onStart will be removed to help users plan their migration.

Consider enhancing the deprecation notice:
   /**
    * onStart is called the first time a task is executed in a run (not before every retry)
    *
-   * @deprecated Use onStartAttempt instead
+   * @deprecated Use onStartAttempt instead. This will be removed in v5.0.0
    */
docs/tasks/overview.mdx (1)

359-362: Consider documenting where these suppressed errors are visible in the dashboard.

The documentation mentions that errors in onSuccess, onComplete, and onFailure are ignored but visible in the dashboard. Consider adding more specific information about where users can find these errors (e.g., in the run details, logs panel, etc.).

Would you like me to suggest more specific documentation about where these errors appear in the dashboard UI?

Also applies to: 390-393, 421-424

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 501a383 and 6170b3d.

⛔ Files ignored due to path filters (1)

references/hello-world/src/trigger/example.ts is excluded by !references/**

📒 Files selected for processing (14)

.changeset/tiny-carrots-rest.md (1 hunks)
apps/webapp/app/components/runs/v3/RunIcon.tsx (1 hunks)
docs/tasks/overview.mdx (9 hunks)
packages/cli-v3/package.json (1 hunks)
packages/core/src/v3/lifecycle-hooks-api.ts (1 hunks)
packages/core/src/v3/lifecycleHooks/index.ts (2 hunks)
packages/core/src/v3/lifecycleHooks/manager.ts (4 hunks)
packages/core/src/v3/lifecycleHooks/types.ts (2 hunks)
packages/core/src/v3/types/tasks.ts (4 hunks)
packages/core/src/v3/workers/taskExecutor.ts (8 hunks)
packages/core/test/taskExecutor.test.ts (2 hunks)
packages/trigger-sdk/src/v3/hooks.ts (2 hunks)
packages/trigger-sdk/src/v3/shared.ts (2 hunks)
packages/trigger-sdk/src/v3/tasks.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{ts,tsx}: Always prefer using isomorphic code like fetch, ReadableStream, etc. instead of Node.js specific code
For TypeScript, we usually use types over interfaces
Avoid enums
No default exports, use function declarations

Files:

packages/core/src/v3/lifecycle-hooks-api.ts
apps/webapp/app/components/runs/v3/RunIcon.tsx
packages/trigger-sdk/src/v3/shared.ts
packages/trigger-sdk/src/v3/tasks.ts
packages/core/src/v3/lifecycleHooks/types.ts
packages/core/src/v3/lifecycleHooks/index.ts
packages/core/test/taskExecutor.test.ts
packages/core/src/v3/types/tasks.ts
packages/trigger-sdk/src/v3/hooks.ts
packages/core/src/v3/workers/taskExecutor.ts
packages/core/src/v3/lifecycleHooks/manager.ts

{packages/core,apps/webapp}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

We use zod a lot in packages/core and in the webapp

Files:

packages/core/src/v3/lifecycle-hooks-api.ts
apps/webapp/app/components/runs/v3/RunIcon.tsx
packages/core/src/v3/lifecycleHooks/types.ts
packages/core/src/v3/lifecycleHooks/index.ts
packages/core/test/taskExecutor.test.ts
packages/core/src/v3/types/tasks.ts
packages/core/src/v3/workers/taskExecutor.ts
packages/core/src/v3/lifecycleHooks/manager.ts

apps/webapp/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/webapp.mdc)

When importing from @trigger.dev/core in the webapp, never import the root package path; always use one of the documented subpath exports from @trigger.dev/core’s package.json

Files:

apps/webapp/app/components/runs/v3/RunIcon.tsx

**/*.test.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Our tests are all vitest

Files:

packages/core/test/taskExecutor.test.ts

**/*.{test,spec}.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{test,spec}.{ts,tsx,js,jsx}: Unit tests must use Vitest
Tests should avoid mocks or stubs and use helpers from @internal/testcontainers when Redis or Postgres are needed
Test files live beside the files under test and should use descriptive describe and it blocks

Files:

packages/core/test/taskExecutor.test.ts

🧠 Learnings (10)

📓 Common learnings

Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-08-18T10:07:17.368Z
Learning: Applies to trigger.config.ts : Configure global task lifecycle hooks (onStart/onSuccess/onFailure) only within trigger.config.ts if needed, not within arbitrary files