diff --git a/docs/cli-dev.mdx b/docs/cli-dev.mdx index ae85cb674..7e67e2687 100644 --- a/docs/cli-dev.mdx +++ b/docs/cli-dev.mdx @@ -51,32 +51,12 @@ yarn dlx trigger.dev@beta dev --debugger ### Concurrently running the terminal -The concurrently package allows you to run multiple package.json scripts at the same time – in this case, your site and Trigger.dev. +Install the concurrently package as a dev dependency: - - - - - - -```bash npm -npm i concurrently -D +```ts +concurrently --raw --kill-others npm:dev:remix npm:dev:trigger ``` -```bash pnpm -pnpm i concurrently -D -``` - -```bash yarn -yarn i concurrently -D -``` - - - - - - - Then add something like this in your package.json scripts. This assumes you're running Next.js so swap that bit out if you're not: ```json @@ -87,7 +67,3 @@ Then add something like this in your package.json scripts. This assumes you're r //... } ``` - - - - \ No newline at end of file diff --git a/docs/deploy-environment-variables.mdx b/docs/deploy-environment-variables.mdx index 2bb30bf02..2bb09b37b 100644 --- a/docs/deploy-environment-variables.mdx +++ b/docs/deploy-environment-variables.mdx @@ -87,7 +87,7 @@ We have a complete set of SDK functions (and REST API) you can use to directly m You could use the SDK functions above but it's much easier to use our `resolveEnvVars` function in your `trigger.config` file. -In this example we're using env vars from Infisical. +In this example we're using env vars from [Infisical](https://infisical.com). ```ts /trigger.config.ts import type { TriggerConfig, ResolveEnvironmentVariablesFunction } from "@trigger.dev/sdk/v3"; @@ -136,13 +136,13 @@ export const config: TriggerConfig = { #### Local development -When you [develop locally](/cli-dev) `resolveEnvVars()` will inject the env vars from Infisical into your local `process.env`. +When you [develop locally](/cli-dev) `resolveEnvVars()` will inject the env vars from [Infisical](https://infisical.com) into your local `process.env`. #### Deploy -When you run the [CLI deploy command](/cli-deploy) directly or using [GitHub Actions](/github-actions) it will sync the environment variables from Infisical to Trigger.dev. This means they'll appear on the Environment Variables page so you can confirm that it's worked. +When you run the [CLI deploy command](/cli-deploy) directly or using [GitHub Actions](/github-actions) it will sync the environment variables from [Infisical](https://infisical.com) to Trigger.dev. This means they'll appear on the Environment Variables page so you can confirm that it's worked. -This means that you need to redeploy your Trigger.dev tasks if you change the environment variables in Infisical. +This means that you need to redeploy your Trigger.dev tasks if you change the environment variables in [Infisical](https://infisical.com). ### The variables return type diff --git a/docs/guides/frameworks/nextjs.mdx b/docs/guides/frameworks/nextjs.mdx index 59b6f79c1..75d2b5273 100644 --- a/docs/guides/frameworks/nextjs.mdx +++ b/docs/guides/frameworks/nextjs.mdx @@ -11,18 +11,291 @@ import CliDevStep from '/snippets/step-cli-dev.mdx'; import CliRunTestStep from '/snippets/step-run-test.mdx'; import CliViewRunStep from '/snippets/step-view-run.mdx'; import UsefulNextSteps from '/snippets/useful-next-steps.mdx'; +import TriggerTaskNextjs from '/snippets/trigger-tasks-nextjs.mdx'; +import NextjsTroubleshootingMissingApiKey from '/snippets/nextjs-missing-api-key.mdx'; +import NextjsTroubleshootingButtonSyntax from '/snippets/nextjs-button-syntax.mdx'; +import WorkerFailedToStartWhenRunningDevCommand from '/snippets/worker-failed-to-start.mdx'; -The following guide should work for both App and Pages router +This guide can be followed for both App and Pages router as well as Server Actions. ## Initial setup - - - - + + + + +## Set your secret key locally + +Set your `TRIGGER_SECRET_KEY` environment variable in your `.env.local` file if using the Next.js App router or `.env` file if using Pages router. This key is used to authenticate with Trigger.dev, so you can trigger runs from your Next.js app. Visit the API Keys page in the dashboard and select the DEV secret key. + +![How to find your secret key](/images/api-keys.png) + +For more information on authenticating with Trigger.dev, see the [API keys page](/apikeys). + +## Triggering your task in Next.js + +Here are the steps to trigger your task in the Next.js App and Pages router and Server Actions. + + + + + + + + + + Add a Route Handler by creating a `route.ts` file (or `route.js` file) in the `app/api` directory like this: `app/api/hello-world/route.ts`. + + + + + + Add this code to your `route.ts` file which imports your task along with `NextResponse` to handle the API route response: + + ```ts app/api/hello-world/route.ts + // Next.js API route support: https://nextjs.org/docs/api-routes/introduction + import type { helloWorldTask } from "@/trigger/example"; + import { tasks } from "@trigger.dev/sdk/v3"; + import { NextResponse } from "next/server"; + + //tasks.trigger also works with the edge runtime + //export const runtime = "edge"; + + export async function GET(request: Request) { + const handle = await tasks.trigger( + "hello-world", + "James" + ); + + return NextResponse.json(handle); + } + ``` + + + + + + + + + + + + + + + + + + + + Create an `actions.ts` file in the `app/api` directory and add this code which imports your `helloWorldTask()` task. Make sure to include `"use server";` at the top of the file. + + ```ts app/api/actions.ts + "use server"; + + import type { helloWorldTask } from "@/trigger/example"; + import { tasks } from "@trigger.dev/sdk/v3"; + + export async function myTask() { + try { + const handle = await tasks.trigger( + "hello-world", + "James" + ); + + return { handle }; + } catch (error) { + console.error(error); + return { + error: "something went wrong", + }; + } + } + ``` + + + + + + For the purposes of this guide, we'll create a button with an `onClick` event that triggers your task. We'll add this to the `page.tsx` file so we can trigger the task by clicking the button. Make sure to import your task and include `"use client";` at the top of your file. + + ```ts app/page.tsx + "use client"; + + import { myTask } from "./actions"; + + export default function Home() { + return ( +
+ +
+ ); + } + ``` + + + + + Run your Next.js app: + + + + ```bash npm + npm run dev + ``` + + ```bash pnpm + pnpm run dev + ``` + + ```bash yarn + yarn dev + ``` + + + + Open your app in a browser, making sure the port number is the same as the one you're running your Next.js app on. For example, if you're running your Next.js app on port 3000, visit: + + ```bash + http://localhost:3000 + ``` + + Run the dev server from Step 2. of the [Initial Setup](/guides/frameworks/nextjs#initial-setup) section above if it's not already running: + + + + ```bash npm + npx trigger.dev@beta dev + ``` + + ```bash pnpm + pnpm dlx trigger.dev@beta dev + ``` + + ```bash yarn + yarn dlx trigger.dev@beta dev + ``` + + + + Then click the button we created in your app to trigger the task. You should see the CLI log the task run with a link to view the logs. + + ![Trigger.dev CLI showing a successful run](/images/trigger-cli-run-success.png) + + Visit the [Trigger.dev dashboard](https://cloud.trigger.dev) to see your run. + + + + + + + + + + + + + + Create an API route in the `pages/api` directory. Then create a `hello-world .ts` (or `hello-world.js`) file for your task and copy this code example: + + ```ts pages/api/hello-world.ts + // Next.js API route support: https://nextjs.org/docs/api-routes/introduction + import { helloWorldTask } from "@/trigger/example"; + import { tasks } from "@trigger.dev/sdk/v3"; + import type { NextApiRequest, NextApiResponse } from "next"; + + export default async function handler( + req: NextApiRequest, + res: NextApiResponse<{ id: string }> + ) { + const handle = await tasks.trigger( + "hello-world", + "James" + ); + + res.status(200).json(handle); + } + ``` + + + + + + + + + + + + + + +## Add your environment variables (optional) + +If you have any environment variables in your tasks, be sure to add them in the dashboard so deployed code runs successfully. In Node.js, these environment variables are accessed in your code using `process.env.MY_ENV_VAR`. + +In the sidebar select the "Environment Variables" page, then press the "New environment variable" +button. ![Environment variables page](/images/environment-variables-page.jpg) + +You can add values for your local dev environment, staging and prod. ![Environment variables +page](/images/environment-variables-panel.jpg) + +You can also add environment variables in code by following the steps on the [Environment Variables page](/deploy-environment-variables#in-your-code). + +## Deploying your task in Next.js + +For this guide, we'll manually deploy your task by running the [CLI deploy command](/cli-deploy) below. Other ways to deploy are listed in the next section. + + + +```bash npm +npx trigger.dev@beta deploy +``` + +```bash pnpm +pnpm dlx trigger.dev@beta deploy +``` + +```bash yarn +yarn dlx trigger.dev@beta deploy +``` + + + +### Other ways to deploy + + + + + +Use GitHub Actions to automatically deploy your tasks whenever new code is pushed and when the `trigger` directory has changes in it. Follow [this guide](/github-actions) to set up GitHub Actions. + + + + + +We're working on adding an official [Vercel integration](/vercel-integration) which you can follow the progress of [here](https://feedback.trigger.dev/p/vercel-integration-3). + + + + + +## Troubleshooting + + + + + diff --git a/docs/images/favicon.png b/docs/images/favicon.png new file mode 100644 index 000000000..f612d076d Binary files /dev/null and b/docs/images/favicon.png differ diff --git a/docs/images/lifecycle-functions.png b/docs/images/lifecycle-functions.png index b99e06a9e..d27936600 100644 Binary files a/docs/images/lifecycle-functions.png and b/docs/images/lifecycle-functions.png differ diff --git a/docs/images/replay-run-action.png b/docs/images/replay-run-action.png index 16d0fab39..ea0a3eb15 100644 Binary files a/docs/images/replay-run-action.png and b/docs/images/replay-run-action.png differ diff --git a/docs/images/replay-run-modal.png b/docs/images/replay-run-modal.png new file mode 100644 index 000000000..f97494b72 Binary files /dev/null and b/docs/images/replay-run-modal.png differ diff --git a/docs/images/trigger-cli-run-success.png b/docs/images/trigger-cli-run-success.png new file mode 100644 index 000000000..76de17971 Binary files /dev/null and b/docs/images/trigger-cli-run-success.png differ diff --git a/docs/limits.mdx b/docs/limits.mdx index c1b340044..31da1126a 100644 --- a/docs/limits.mdx +++ b/docs/limits.mdx @@ -4,6 +4,7 @@ description: "There are some hard and soft limits in v3 that you might hit." --- import SoftLimit from '/snippets/soft-limit.mdx'; +import RateLimitHitUseBatchTrigger from '/snippets/rate-limit-hit-use-batchtrigger.mdx'; ## Concurrency limits @@ -24,7 +25,7 @@ These are the default limits on a free account. Generally speaking each SDK call is an API call. -The most common cause of hitting the API rate limit is if you're calling `trigger()` on a task in a loop, instead of doing this use `batchTrigger()` which will trigger multiple tasks in a single API call. You can have up to 100 tasks in a single batch trigger call. + ## Schedules diff --git a/docs/mint.json b/docs/mint.json index 6586897a1..fb88187e5 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -67,6 +67,10 @@ { "source": "/v3/:slug*", "destination": "/:slug*" + }, + { + "source": "/reattempting-replaying", + "destination": "/replaying" } ], @@ -124,7 +128,7 @@ "versioning", "machines", "idempotency", - "reattempting-replaying", + "replaying", "tags", "notifications", "run-usage" diff --git a/docs/open-source-self-hosting.mdx b/docs/open-source-self-hosting.mdx index 0ff19b429..342224478 100644 --- a/docs/open-source-self-hosting.mdx +++ b/docs/open-source-self-hosting.mdx @@ -277,3 +277,11 @@ By default, the Trigger.dev webapp sends telemetry data to our servers. This dat ```bash TRIGGER_TELEMETRY_DISABLED=1 ``` + +## Login via the CLI + +To avoid being redirected to the Cloud login page when using the CLI, you can specify the URL of your self-hosted instance with the `-a` flag. For example: + +``` +npx trigger.dev@beta login -a http://example.com +``` \ No newline at end of file diff --git a/docs/reattempting-replaying.mdx b/docs/reattempting-replaying.mdx deleted file mode 100644 index 80a72d39f..000000000 --- a/docs/reattempting-replaying.mdx +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Reattempting & Replaying" -description: "You can reattempt a task that has failed all of its attempts. You can also replay a task with a new version of your code." ---- - -import ComingSoon from "/snippets/coming-soon-generic.mdx" - -## Replaying - -A replay is a copy of a run with the same payload but against the latest version in that environment. This is useful if something went wrong and you want to try again with the latest version of your code. - -### Replaying from the UI - - - - Select a task, then in the bottom right click "Replay" ![Select a task, then in the bottom right - click "Replay"](/images/replay-run-action.png) - - - - - ![On the runs page, press the triple dot button](/images/replay-runs-list.png) - - ![Click replay](/images/replay-runs-list-popover.png) - - - - -### Replaying using the SDK - -You can replay a run using the SDK: - -```ts -const replayedRun = await runs.replay(run.id); -``` - -When you call `trigger()` or `batchTrigger()` on a task you receive back a run handle which has an `id` property. You can use that `id` to replay the run. - -You can also access the run id from inside a run. You could write this to your database and then replay it later. - -```ts -export const simpleChildTask = task({ - id: "simple-child-task", - run: async (payload, { ctx }) => { - // the run ID (and other useful info) is in ctx - const runId = ctx.run.id; - }, -}); -``` - -### Reattempting - -Tasks can [automatically reattempt](/errors-retrying) based on the settings you provide. - -Sometimes a task will fail all of its attempts. In that case, you can continue reattempting. - - diff --git a/docs/replaying.mdx b/docs/replaying.mdx new file mode 100644 index 000000000..8b21de6ac --- /dev/null +++ b/docs/replaying.mdx @@ -0,0 +1,70 @@ +--- +title: "Replaying" +description: "A replay is a copy of a run with the same payload but against the latest version in that environment. This is useful if something went wrong and you want to try again with the latest version of your code." +--- + +### Replaying from the UI + + + + + + ![Select a task, then in the bottom right + click "Replay"](/images/replay-run-action.png) + + + You can edit the payload (if available) and choose the environment to replay the run in. + + ![Select a task, then in the bottom right + click "Replay"](/images/replay-run-modal.png) + + + + + + + ![On the runs page, press the triple dot button](/images/replay-runs-list.png) + + ![Click replay](/images/replay-runs-list-popover.png) + + + + +### Replaying using the SDK + +You can replay a run using the SDK: + +```ts +const replayedRun = await runs.replay(run.id); +``` + +When you call `trigger()` or `batchTrigger()` on a task you receive back a run handle which has an `id` property. You can use that `id` to replay the run. + +You can also access the run id from inside a run. You could write this to your database and then replay it later. + +```ts +export const simpleChildTask = task({ + id: "simple-child-task", + run: async (payload, { ctx }) => { + // the run ID (and other useful info) is in ctx + const runId = ctx.run.id; + }, +}); +``` + +### Bulk replaying + +You can replay multiple runs at once by selecting them from the table on the Runs page using the checkbox on the left hand side of the row. Then click the "Replay runs" button from the bulk action bar that appears at the bottom of the screen. + +This is especially useful if you have lots of failed runs and want to run them all again. To do this, first filter the runs by the status you want, then select all the runs you want to replay and click the "Replay runs" button from the bulk action bar at the bottom of the page. + +