github-featured/triggerdotdev--trigger.dev
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

v3 docs improvements (#993)

Browse Source 
* WIP on adding versioning to the docs to make it less confusing

* Link to v3 from v2 and vice versa. Also added a warning to the v2 docs

* Make v3 the default

* Trigger config docs about bundling

* Next stpe to triggering guide from tasks overview

* Server actions guidance for triggering

* Moved the trigger.config docs to the end of fundamentals
This commit is contained in:
Matt Aitken
2024-04-02 14:32:28 +01:00
committed by GitHub
parent 28837f39b3
commit afe7f410c7
10 changed files with 251 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/documentation/introduction.mdx
+4 -2
View File
@@ -1,9 +1,11 @@
---
title: "Getting Started: Introduction"
title: "v2: Introduction"
sidebarTitle: "Introduction"
description: "Welcome to the Trigger.dev documentation."
description: "Welcome to the Trigger.dev (v2) documentation."
---
<Warning>These are the docs for Trigger.dev v2. You probably want [the v3 docs](/v3).</Warning>
Trigger.dev is an open source framework for creating long-running Jobs directly in your app with API Integrations, webhooks, scheduling and delays. You can reliably run Jobs that wouldn't normally work in serverless environments (like Vercel) because of timeouts.
You can use [Trigger.dev Cloud](https://cloud.trigger.dev) or [Self-host Trigger.dev](/documentation/guides/self-hosting) on your own infrastructure.
docs/images/v3/auto-instrumentation.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 105 KiB

docs/mint.json
+36 -7
View File
@@ -2,6 +2,7 @@
"$schema": "https://mintlify.com/schema.json",
"name": "Trigger.dev",
"openapi": ["/openapi.yml"],
"versions": ["v3 (Developer Preview)", "v2"],
"logo": {
"dark": "/logo/dark.png",
"light": "/logo/light.png",
@@ -37,22 +38,34 @@
"url": "https://discord.gg/kA47vcd8P6"
}
],
"primaryTab": {
"name": "Home"
},
"tabs": [
{
"name": "Integrations",
"url": "integrations"
"url": "integrations",
"version": "v2"
},
{
"name": "Reference",
"url": "sdk"
"url": "sdk",
"version": "v2"
},
{
"name": "Examples",
"url": "https://trigger.dev/apis"
"url": "https://trigger.dev/apis",
"version": "v2"
},
{
"name": "v3 Developer Preview",
"url": "v3"
"url": "https://trigger.dev/docs/v3",
"version": "v2"
},
{
"name": "v2",
"url": "https://trigger.dev/docs",
"version": "v3 (Developer Preview)"
}
],
"redirects": [
@@ -76,6 +89,7 @@
"navigation": [
{
"group": "Getting Started",
"version": "v2",
"pages": [
"documentation/introduction",
{
@@ -107,6 +121,7 @@
},
{
"group": "Concepts",
"version": "v2",
"pages": [
"documentation/concepts/what-is-triggerdotdev",
"documentation/concepts/limits",
@@ -142,6 +157,7 @@
},
{
"group": "Guides",
"version": "v2",
"pages": [
{
"group": "Frameworks",
@@ -226,6 +242,7 @@
},
{
"group": "Community & Support",
"version": "v2",
"pages": [
"documentation/get-help",
"documentation/faq",
@@ -430,14 +447,17 @@
},
{
"group": "Overview",
"version": "v2",
"pages": ["examples/introduction"]
},
{
"group": "",
"version": "v3 (Developer Preview)",
"pages": ["v3/introduction"]
},
{
"group": "Getting Started",
"version": "v3 (Developer Preview)",
"pages": [
"v3/quick-start",
"v3/upgrading-from-v2",
@@ -448,6 +468,7 @@
},
{
"group": "Fundamentals",
"version": "v3 (Developer Preview)",
"pages": [
"v3/trigger-folder",
"v3/tasks-overview",
@@ -456,15 +477,18 @@
{
"group": "Task types",
"pages": ["v3/tasks-regular", "v3/tasks-scheduled", "v3/tasks-zod", "v3/tasks-webhooks"]
}
},
"v3/trigger-config"
]
},
{
"group": "Development",
"version": "v3 (Developer Preview)",
"pages": ["v3/cli-dev", "v3/run-tests"]
},
{
"group": "Deployment",
"version": "v3 (Developer Preview)",
"pages": [
"v3/deploy-environment-variables",
"v3/cli-deploy",
@@ -477,6 +501,7 @@
},
{
"group": "Writing tasks",
"version": "v3 (Developer Preview)",
"pages": [
"v3/writing-tasks-introduction",
"v3/logging",
@@ -506,6 +531,7 @@
},
{
"group": "Dashboard",
"version": "v3 (Developer Preview)",
"pages": [
"v3/dashboard-overview",
"v3/dashboard-runs",
@@ -515,6 +541,7 @@
},
{
"group": "API reference",
"version": "v3 (Developer Preview)",
"pages": [
{
"group": "Functions",
@@ -558,12 +585,12 @@
"v3/reference-cli-build",
"v3/reference-cli-who-am-i"
]
},
"v3/reference-trigger-config"
}
]
},
{
"group": "Architecture",
"version": "v3 (Developer Preview)",
"pages": [
"v3/architecture-how-it-works",
"v3/architecture-multi-tenant-queue",
@@ -572,10 +599,12 @@
},
{
"group": "Open source",
"version": "v3 (Developer Preview)",
"pages": ["v3/github-repo", "v3/open-source-self-hosting", "v3/open-source-contributing"]
},
{
"group": "Help",
"version": "v3 (Developer Preview)",
"pages": [
"v3/help-faqs",
"v3/community",
docs/v3/errors-retrying.mdx
+2 -2
View File
@@ -7,12 +7,12 @@ When an uncaught error is thrown inside your task, that task attempt will fail.
You can configure retrying in two ways:
1. In your [trigger.config file](/v3/reference-trigger-config) you can set the default retrying behavior for all tasks.
1. In your [trigger.config file](/v3/trigger-config) you can set the default retrying behavior for all tasks.
2. On each task you can set the retrying behavior.
<Note>
By default when you create your project using the CLI init command we disabled retrying in the DEV
environment. You can enable it in your [trigger.config file](/v3/reference-trigger-config).
environment. You can enable it in your [trigger.config file](/v3/trigger-config).
</Note>
## A simple example with OpenAI
docs/v3/logging.mdx
+7 -5
View File
@@ -38,18 +38,20 @@ Tracing is a way to follow the flow of your code. It's very useful for debugging
Trigger.dev uses OpenTelemetry tracing under the hood. With automatic tracing for many things like task triggering, task attempts, HTTP requests, and more.
### Automatic instrumentation
| Name | Description |
| ------------- | -------------------------------- |
| Task triggers | Task triggers. |
| Task attempts | Task attempts. |
| HTTP requests | HTTP requests made by your code. |
| OpenAI | OpenAI SDK calls. |
We want to provide automatic instrumentation for as many things as possible. Please do [request any automatic instrumentation](https://github.com/triggerdotdev/trigger.dev/issues/new?template=instrumentation_request.yml) you would like to see.
### Adding instrumentations
## Add custom traces
![The run log
](/images/v3/auto-instrumentation.png)
You can [add instrumentations](/v3/trigger-config#instrumentations). The Prisma one above will automatically trace all Prisma queries.
### Add custom traces
If you want to add custom traces to your code, you can use the `logger.trace` function. It will create a new OTEL trace and you can set attributes on it.
docs/v3/reference-trigger-config.mdx
-7
View File
@@ -1,7 +0,0 @@
---
title: "The trigger.config.js file"
sidebarTitle: "trigger.config file"
description: "This file is used to configure some settings for your project."
---
<Snippet file="incomplete-docs.mdx" />
docs/v3/tasks-overview.mdx
+3
View File
@@ -149,6 +149,9 @@ When a task attempt fails, the `onError` function is called. It's useful for sen
## Next steps
<CardGroup>
<Card title="Triggering" icon="bolt" href="/v3/triggering">
Learn how to trigger your tasks from your code.
</Card>
<Card title="Writing tasks" icon="wand-magic-sparkles" href="/v3/writing-tasks-introduction">
Tasks are the core of Trigger.dev. Learn how to write them.
</Card>
docs/v3/trigger-config.mdx
+127
View File
@@ -0,0 +1,127 @@
---
title: "The trigger.config.ts file"
sidebarTitle: "trigger.config file"
description: "This file is used to configure your project and how it's bundled."
---
Let's take a look at a basic `trigger.config.ts` file. This is generated for you when you follow [the quick start guide](/v3/quick-start). This file is used to configure your project and how it's bundled.
```ts trigger.config.ts
import type { TriggerConfig } from "@trigger.dev/sdk/v3";
export const config: TriggerConfig = {
//Your project ref (you can see it on the Project settings page in the dashboard)
project: "proj_gtcwttqhhtlasxgfuhxs",
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 paths for your trigger folders
triggerDirectories: ["./trigger"],
};
```
Most of the time you don't need to change anything in this file, or if you do then we will tell you when you the run the CLI command.
## 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:
![The run log
](/images/v3/auto-instrumentation.png)
Here we add Prisma and OpenAI instrumentations to your `trigger.config.ts` file.
```ts trigger.config.ts
import type { TriggerConfig } from "@trigger.dev/sdk/v3";
import { PrismaInstrumentation } from "@prisma/instrumentation";
import { OpenAIInstrumentation } from "@traceloop/instrumentation-openai";
export const config: TriggerConfig = {
//..other stuff
instrumentations: [new PrismaInstrumentation(), new OpenAIInstrumentation()],
};
```
## ESM-only packages
We'll let you know when run the CLI dev command if this is a problem. Some packages are ESM-only so they don't work directly from CJS when using Node.js. In that case you need to add them to the `dependenciesToBundle` array in your `trigger.config.ts` file.
```ts trigger.config.ts
import type { TriggerConfig } from "@trigger.dev/sdk/v3";
export const config: TriggerConfig = {
//..other stuff
//either regex or strings of package names
dependenciesToBundle: [/@sindresorhus/, "escape-string-regexp"],
};
```
## Prisma (and other generators)
<Accordion title="The Prisma error you might see">
```bash
✘ [ERROR] Error: @prisma/client did not initialize yet. Please run "prisma generate" and try to import it again.
In case this error is unexpected for you, please report it in
https://pris.ly/prisma-prisma-bug-report
at new PrismaClient (/app/node_modules/.prisma/client/default.js:43:11)
at Object.<anonymous> (/lib/prisma.ts:7:33)
at Module.\_compile (node:internal/modules/cjs/loader:1356:14)
at Object.Module.\_extensions..js (node:internal/modules/cjs/loader:1414:10)
at Module.load (node:internal/modules/cjs/loader:1197:32)
at Function.Module.\_load (node:internal/modules/cjs/loader:1013:12)
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:128:12)
at node:internal/main/run_main_module:28:49
```
</Accordion>
Prisma works by generating a client from your `prisma.schema` file. This means you need to do a couple of things to get it to work with Trigger:
<Steps>
<Step title="package.json postinstall `prisma generate`">
```json
{
"scripts": {
"postinstall": "prisma generate"
}
}
```
Anything you put in `postinstall` will be run as part of the install step. This is how Next.js recommends you set up Prisma anyway.
</Step>
<Step title="Add prisma and the schema to trigger.config.ts">
```ts trigger.config.ts
import type { TriggerConfig } from "@trigger.dev/sdk/v3";
export const config: TriggerConfig = {
//..other stuff
additionalFiles: ["./prisma/schema.prisma"],
additionalPackages: ["prisma@5.11.0"],
};
```
This tells Trigger to bundle the Prisma client and the schema file.
</Step>
</Steps>
## Troubleshooting
If you have an issue with bundling let us know on [Discord](https://trigger.dev/discord) or [via email](https://trigger.dev/contact).
docs/v3/trigger-folder.mdx
+2 -2
View File
@@ -11,7 +11,7 @@ We automatically bundle everything for your tasks. This includes:
- Imported npm packages.
- Other imports from your code.
This means you shouldn't need to think about what gets bundled. Just write your tasks and we'll take care of the rest.
Mostly this means you shouldn't need to think about what gets bundled. Just write your tasks and we'll take care of the rest. If you need to alter the bundling you use the [trigger.config file](/v3/trigger-config).
## Multiple `/trigger` folders
@@ -22,4 +22,4 @@ You can have multiple `/trigger` folders in your repository.
### (Optional) configuration
It is possible to manually set one or more folders as `/trigger` folders in your `trigger.config` file. View the [trigger.config documentation](/v3/referece-trigger-config) for more information.
It is possible to manually set one or more folders as `/trigger` folders in your [trigger.config file](/v3/trigger-config).
docs/v3/triggering.mdx
+70
View File
@@ -23,6 +23,8 @@ You can trigger any task from your backend code, using either `trigger()` or `ba
Trigger.dev API key to the world.
</Note>
You can use Next.js Server Actions but [you need to be careful with bundling](#next-js-server-actions).
### Authentication
When you trigger a task from your backend code, you need to set the `TRIGGER_SECRET_KEY` environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. [More info on API keys](/v3/apikeys).
@@ -188,3 +190,71 @@ export const batchParentTask = task({
},
});
```
## Next.js Server Actions
Server Actions allow you to call your backend code without creating API routes. This is very useful for triggering tasks but you need to be careful you don't accidentally bundle the Trigger.dev SDK into your frontend code.
If you see an error like this then you've bundled `@trigger.dev/sdk` into your frontend code:
```bash
Module build failed: UnhandledSchemeError: Reading from "node:crypto" is not handled by plugins (Unhandled scheme).
Module build failed: UnhandledSchemeError: Reading from "node:process" is not handled by plugins (Unhandled scheme).
Webpack supports "data:" and "file:" URIs by default.
You may need an additional plugin to handle "node:" URIs.
```
When you use server actions that use `@trigger.dev/sdk`:
- The file can't have any React components in it.
- The file should have `"use server"` on the first line.
Here's an example of how to do it with a component that calls the server action and the actions file:
<CodeGroup>
```tsx app/page.tsx
"use client";
import { create } from "@/app/actions";
export default function Home() {
return (
<main className="flex min-h-screen flex-col items-center justify-between p-24">
<button
onClick={async () => {
const handle = await create();
console.log(handle);
}}
>
Create a thing
</button>
</main>
);
}
```
```tsx app/actions.ts
"use server";
import { createAvatar } from "@/trigger/create-avatar";
export async function create() {
try {
const handle = await createAvatar.trigger({
payload: {
userImage: "http://...",
},
});
return { handle };
} catch (error) {
console.error(error);
return {
error: "something went wrong",
};
}
}
```
</CodeGroup>