docs: Manual setup guide #2358
Merged
docs: Manual setup guide #2358
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit introduces a new "Manual setup" guide for setting up Trigger.dev in projects, specifically focused on monorepo configurations. The guide outlines two primary approaches for monorepos: creating a dedicated tasks package and integrating tasks directly within apps. This detailed documentation aims to help developers manually configure their projects, bypassing automated steps, and understanding the setup better. - Provides step-by-step instructions for both 'Tasks as a package' and 'Tasks in apps' approaches. - Includes example configurations for various package managers, environment setups, and runtime options. - Enhances user understanding of Trigger.dev's configuration requirements in complex monorepo environments. The purpose of adding this guide is to enable developers to seamlessly integrate Trigger.dev into their monorepos, whether they choose to abstract tasks into packages or embed them within individual applications. This flexibility supports diverse project structures while maintaining consistency with Trigger.dev's operational prerequisites.
The 'tasks as package' section in the documentation had an incorrect example under 'Use tasks in your apps' which needed correction to align with the actual package usage. - Fixed incorrect import of tasks by updating to the correct import from '@repo/tasks/trigger'. - Updated the syntax to use 'tasks.trigger' with type parameters, following the new pattern established for triggering tasks with TypeScript. - Added error handling to catch and log errors during task execution, returning a meaningful error message instead of just failing silently. This update ensures developers have an accurate reference when implementing tasks in their applications, especially given the breaking changes in TypeScript compatibility due to recent package updates.
The recent Zod package updates from version 3 to 4 introduce breaking changes in TypeScript compatibility that require adjustments in our project configuration files. The primary updates involve adding type annotations and modifying import statements to support the shift without breaking existing functionality. - Updated `package.json` and initialization files to align with new compatibility requirements. - Modified server task examples to explicitly use type imports for improved error handling and consistency. - Adjusted workspace and project settings to maintain compatibility and improve configuration clarity. - Provided references to current examples for better implementation guidance.
|
WalkthroughThis change introduces a new documentation file, Estimated code review effort🎯 2 (Simple) | ⏱️ ~7 minutes Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
docs/docs.json (1)
202-225: Duplicate “Self-hosting” groups may confuse the navigationTwo adjacent groups share the exact same
"group": "Self-hosting"label but list different pages. Mintlify renders the label verbatim, so the sidebar will show two “Self-hosting” sections back-to-back.
Consider merging the page lists into a single group or renaming one of them (e.g. “Self-hosting – OSS guide”) to avoid reader confusion.docs/manual-setup.mdx (2)
34-37: Use the standardnpm installverb instead ofnpm add
npm addis not an officially documented alias (it currently works only because it forwards toinstallin recent npm versions).
For consistency with the other package-manager examples and for compatibility with older npm versions, switch tonpm install/npm i.-```bash npm -npm add @trigger.dev/sdk@v4-beta -npm add --save-dev @trigger.dev/build@v4-beta +```bash npm +npm install @trigger.dev/sdk@v4-beta +npm install --save-dev @trigger.dev/build@v4-beta
98-129: Pin all Trigger.dev packages to the same version to prevent subtle mismatchesThe snippet correctly pins
trigger.dev,@trigger.dev/buildand@trigger.dev/sdkto4.0.0-v4-beta.26, but the earlier installation commands still use the un-pinned@v4-betatag.
Recommend showing the pinned variant in every install example (npm/pnpm/yarn/bun) so readers don’t accidentally mix CLI and SDK patch versions.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/docs.json(13 hunks)docs/manual-setup.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (18)
📓 Common learnings
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : ALWAYS generate Trigger.dev tasks using the `task` function from `trigger.dev/sdk/v3` and export them as shown in the correct pattern.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : Build extensions such as `additionalFiles`, `additionalPackages`, `aptGet`, `emitDecoratorMetadata`, `prismaExtension`, `syncEnvVars`, `puppeteer`, `ffmpeg`, and `esbuildPlugin` must be configured in `trigger.config.ts` as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : You MUST use `trigger.dev/sdk/v3` when writing Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing schema tasks, use `schemaTask` from `trigger.dev/sdk/v3` and validate payloads as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : Global lifecycle hooks, telemetry, runtime, machine settings, log level, max duration, and build configuration must be set in `trigger.config.ts` as shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : The `trigger.config.ts` file must use `defineConfig` from `trigger.dev/sdk/v3` and follow the configuration structure shown.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using retry, queue, machine, or maxDuration options, configure them as shown in the examples for Trigger.dev tasks.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing scheduled (cron) tasks, use `schedules.task` from `trigger.dev/sdk/v3` and follow the shown patterns.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When triggering a task from backend code, use `tasks.trigger`, `tasks.batchTrigger`, or `tasks.triggerAndPoll` as shown in the examples.
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using lifecycle hooks (`init`, `cleanup`, `onStart`, `onSuccess`, `onFailure`, `handleError`), implement them as shown in the examples for Trigger.dev tasks.
📚 Learning: references to old urls in `docs/mint.json` may be intentional redirects and should remain as is unle...
Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#1306
File: docs/snippets/useful-next-steps.mdx:4-4
Timestamp: 2024-09-23T13:07:08.455Z
Learning: References to old URLs in `docs/mint.json` may be intentional redirects and should remain as is unless otherwise specified.
Applied to files:
docs/docs.json
📚 Learning: when suggesting changes to documentation, note that the team prefers to keep them simple to avoid co...
Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#1306
File: docs/github-actions.mdx:59-59
Timestamp: 2024-10-12T01:08:24.066Z
Learning: When suggesting changes to documentation, note that the team prefers to keep them simple to avoid confusion.
Applied to files:
docs/docs.json
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : when triggering a task from backend code, use `tasks.tr...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When triggering a task from backend code, use `tasks.trigger`, `tasks.batchTrigger`, or `tasks.triggerAndPoll` as shown in the examples.
Applied to files:
docs/docs.jsondocs/manual-setup.mdx
📚 Learning: in the docs.json configuration for the trigger.dev documentation (mintlify system), both "tags": ["v...
Learnt from: nicktrn
PR: triggerdotdev/trigger.dev#2155
File: docs/docs.json:179-183
Timestamp: 2025-06-06T16:54:23.316Z
Learning: In the docs.json configuration for the Trigger.dev documentation (Mintlify system), both "tags": ["v4"] and "tag": "v4" properties can be used together and work correctly, even though this behavior is undocumented and may not work in local development environments.
Applied to files:
docs/docs.json
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : you must use `@trigger.dev/sdk/v3` when writing trigger...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : You MUST use `trigger.dev/sdk/v3` when writing Trigger.dev tasks.
Applied to files:
docs/docs.jsondocs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : always generate trigger.dev tasks using the `task` func...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : ALWAYS generate Trigger.dev tasks using the `task` function from `trigger.dev/sdk/v3` and export them as shown in the correct pattern.
Applied to files:
docs/docs.jsondocs/manual-setup.mdx
📚 Learning: applies to trigger.config.ts : build extensions such as `additionalfiles`, `additionalpackages`, `ap...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : Build extensions such as `additionalFiles`, `additionalPackages`, `aptGet`, `emitDecoratorMetadata`, `prismaExtension`, `syncEnvVars`, `puppeteer`, `ffmpeg`, and `esbuildPlugin` must be configured in `trigger.config.ts` as shown.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : when using retry, queue, machine, or maxduration option...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using retry, queue, machine, or maxDuration options, configure them as shown in the examples for Trigger.dev tasks.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to trigger.config.ts : global lifecycle hooks, telemetry, runtime, machine settings, log lev...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : Global lifecycle hooks, telemetry, runtime, machine settings, log level, max duration, and build configuration must be set in `trigger.config.ts` as shown.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : when implementing scheduled (cron) tasks, use `schedule...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing scheduled (cron) tasks, use `schedules.task` from `trigger.dev/sdk/v3` and follow the shown patterns.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to trigger.config.ts : the `trigger.config.ts` file must use `defineconfig` from `@trigger.d...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to trigger.config.ts : The `trigger.config.ts` file must use `defineConfig` from `trigger.dev/sdk/v3` and follow the configuration structure shown.
Applied to files:
docs/manual-setup.mdx
📚 Learning: before generating any code for trigger.dev tasks, verify: (1) are you importing from `@trigger.dev/s...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Before generating any code for Trigger.dev tasks, verify: (1) Are you importing from `trigger.dev/sdk/v3`? (2) Have you exported every task? (3) Have you generated any deprecated code patterns?
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : you must `export` every task, including subtasks, in tr...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : You MUST `export` every task, including subtasks, in Trigger.dev task files.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : when implementing schema tasks, use `schematask` from `...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When implementing schema tasks, use `schemaTask` from `trigger.dev/sdk/v3` and validate payloads as shown.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : when using lifecycle hooks (`init`, `cleanup`, `onstart...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : When using lifecycle hooks (`init`, `cleanup`, `onStart`, `onSuccess`, `onFailure`, `handleError`), implement them as shown in the examples for Trigger.dev tasks.
Applied to files:
docs/manual-setup.mdx
📚 Learning: applies to **/trigger/**/*.{ts,tsx,js,jsx} : the `run` function contains your task logic in trigger....
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : The `run` function contains your task logic in Trigger.dev tasks.
Applied to files:
docs/manual-setup.mdx
📚 Learning: when asked about trigger.dev task implementation, you must: (1) first use code patterns from this gu...
Learnt from: CR
PR: triggerdotdev/trigger.dev#0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-07-18T17:50:25.014Z
Learning: When asked about Trigger.dev task implementation, you MUST: (1) FIRST use code patterns from this guide, (2) NEVER suggest deprecated approaches, (3) VERIFY your response against the patterns shown here.
Applied to files:
docs/manual-setup.mdx
🔇 Additional comments (1)
docs/docs.json (1)
453-456: 👍openapilist reformatted – no issues spottedThe new multiline array is syntactically correct and improves diffability.
Comment on lines
+190
to
+203
| import { task } from "@trigger.dev/sdk"; | ||
|
|
||
| export const helloWorld = task({ | ||
| id: "hello-world", | ||
| run: async (payload: { name: string }) => { | ||
| console.log(`Hello ${payload.name}!`); | ||
|
|
||
| return { | ||
| message: `Hello ${payload.name}!`, | ||
| timestamp: new Date().toISOString(), | ||
| }; | ||
| }, | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
💡 Verification agent
🧩 Analysis chain
Import path deviates from documented internal guideline – confirm before publishing
The example task imports from @trigger.dev/sdk, whereas the current engineering guideline (see .cursor/rules/writing-tasks.mdc) mandates importing from trigger.dev/sdk/v3.
If the guideline has been superseded for the v4 beta, please update the rule set; otherwise adjust the import here.
🏁 Script executed:
#!/bin/bash
# Search the repository for v4-beta examples to confirm the intended import path
rg --no-heading --line-number $'from .+trigger\\.dev/sdk' | head -n 20Length of output: 1898
Update import to use the v3 SDK path
The example in docs/manual-setup.mdx (lines 190–203) is currently importing from the root package. Per our internal guideline for v3 tasks, it must import from the v3 entrypoint. Please update:
- import { task } from "@trigger.dev/sdk";
+ import { task } from "@trigger.dev/sdk/v3";📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| import { task } from "@trigger.dev/sdk"; | |
| export const helloWorld = task({ | |
| id: "hello-world", | |
| run: async (payload: { name: string }) => { | |
| console.log(`Hello ${payload.name}!`); | |
| return { | |
| message: `Hello ${payload.name}!`, | |
| timestamp: new Date().toISOString(), | |
| }; | |
| }, | |
| }); | |
| ``` | |
| import { task } from "@trigger.dev/sdk/v3"; | |
| export const helloWorld = task({ | |
| id: "hello-world", | |
| run: async (payload: { name: string }) => { | |
| console.log(`Hello ${payload.name}!`); | |
| return { | |
| message: `Hello ${payload.name}!`, | |
| timestamp: new Date().toISOString(), | |
| }; | |
| }, | |
| }); |
🤖 Prompt for AI Agents
In docs/manual-setup.mdx around lines 190 to 203, the import statement for the
task should be updated to use the v3 SDK path instead of the root package.
Change the import from "@trigger.dev/sdk" to the correct v3 entrypoint path as
per internal guidelines to ensure compatibility with v3 tasks.
samejr
approved these changes
Aug 7, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.