@trigger.dev/sdk 4.5.0-rc.6 → 4.5.0-rc.7

package/docs/config/extensions/puppeteer.mdx

@@ -0,0 +1,30 @@
+---
+title: "Puppeteer"
+sidebarTitle: "puppeteer"
+description: "Use the puppeteer build extension to enable support for Puppeteer in your project"
+---
+
+<ScrapingWarning />
+
+To use Puppeteer in your project, add these build settings to your `trigger.config.ts` file:
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { puppeteer } from "@trigger.dev/build/extensions/puppeteer";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [puppeteer()],
+  },
+});
+```
+
+And add the following environment variable in your Trigger.dev dashboard on the Environment Variables page:
+
+```bash
+PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable",
+```
+
+Follow [this example](/guides/examples/puppeteer) to get setup with Trigger.dev and Puppeteer in your project.

package/docs/config/extensions/pythonExtension.mdx

@@ -0,0 +1,182 @@
+---
+title: "Python"
+sidebarTitle: "pythonExtension"
+description: "Use the python build extension to add support for executing Python scripts in your project"
+---
+
+If you need to execute Python scripts in your Trigger.dev project, you can use the `pythonExtension` build extension via the `@trigger.dev/python` package.
+
+First, you'll need to install the `@trigger.dev/python` package:
+
+```bash
+npm add @trigger.dev/python
+```
+
+Then, you can use the `pythonExtension` build extension in your `trigger.config.ts` file:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { pythonExtension } from "@trigger.dev/python/extension";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [pythonExtension()],
+  },
+});
+```
+
+This will take care of adding python to the build image and setting up the necessary environment variables to execute Python scripts. You can then use our `python` utilities in the `@trigger.dev/python` package to execute Python scripts in your tasks. For example, running a Python script inline in a task:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { python } from "@trigger.dev/python";
+
+export const myScript = task({
+  id: "my-python-script",
+  run: async () => {
+    const result = await python.runInline(`print("Hello, world!")`);
+    return result.stdout;
+  },
+});
+```
+
+## Adding python scripts
+
+You can automatically add python scripts to your project using the `scripts` option in the `pythonExtension` function. This will copy the specified scripts to the build directory during the deploy process. For example:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { pythonExtension } from "@trigger.dev/python/extension";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      pythonExtension({
+        scripts: ["./python/**/*.py"],
+      }),
+    ],
+  },
+});
+```
+
+This will copy all Python files in the `python` directory to the build directory during the deploy process. You can then execute these scripts using the `python.runScript` function:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { python } from "@trigger.dev/python";
+
+export const myScript = task({
+  id: "my-python-script",
+  run: async () => {
+    const result = await python.runScript("./python/my_script.py", ["hello", "world"]);
+    return result.stdout;
+  },
+});
+```
+
+<Note>
+  The pythonExtension will also take care of moving the scripts to the correct location during `dev`
+  mode, so you can use the same exact path in development as you do in production.
+</Note>
+
+## Using requirements files
+
+If you have a `requirements.txt` file in your project, you can use the `requirementsFile` option in the `pythonExtension` function to install the required packages during the build process. For example:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { pythonExtension } from "@trigger.dev/python/extension";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      pythonExtension({
+        requirementsFile: "./requirements.txt",
+      }),
+    ],
+  },
+});
+```
+
+This will install the packages specified in the `requirements.txt` file during the build process. You can then use these packages in your Python scripts.
+
+<Note>
+  The `requirementsFile` option is only available in production mode. In development mode, you can
+  install the required packages manually using the `pip` command.
+</Note>
+
+## Virtual environments
+
+If you are using a virtual environment in your project, you can use the `devPythonBinaryPath` option in the `pythonExtension` function to specify the path to the Python binary in the virtual environment. For example:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { pythonExtension } from "@trigger.dev/python/extension";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      pythonExtension({
+        devPythonBinaryPath: ".venv/bin/python",
+      }),
+    ],
+  },
+});
+```
+
+This has no effect in production mode, but in development mode, it will use the specified Python binary to execute Python scripts.
+
+## Streaming output
+
+All of the `python` functions have a streaming version that allows you to stream the output of the Python script as it runs. For example:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { python } from "@trigger.dev/python";
+
+export const myStreamingScript = task({
+  id: "my-streaming-python-script",
+  run: async () => {
+    // You don't need to await the result
+    const result = python.stream.runScript("./python/my_script.py", ["hello", "world"]);
+
+    // result is an async iterable/readable stream
+    for await (const chunk of streamingResult) {
+      console.log(chunk);
+    }
+  },
+});
+```
+
+## Environment variables
+
+We automatically inject the environment variables in the `process.env` object when running Python scripts. You can access these environment variables in your Python scripts using the `os.environ` dictionary. For example:
+
+```python
+import os
+
+print(os.environ["MY_ENV_VAR"])
+```
+
+You can also pass additional environment variables to the Python script using the `env` option in the `python.runScript` function. For example:
+
+```ts
+import { task } from "@trigger.dev/sdk";
+import { python } from "@trigger.dev/python";
+
+export const myScript = task({
+  id: "my-python-script",
+  run: async () => {
+    const result = await python.runScript("./python/my_script.py", ["hello", "world"], {
+      env: {
+        MY_ENV_VAR: "my value",
+      },
+    });
+    return result.stdout;
+  },
+});
+```

package/docs/config/extensions/syncEnvVars.mdx

@@ -0,0 +1,291 @@
+---
+title: "Sync env vars"
+sidebarTitle: "syncEnvVars"
+description: "Use the syncEnvVars build extension to automatically sync environment variables to Trigger.dev"
+---
+
+The `syncEnvVars` build extension will sync env vars from another service into Trigger.dev before the deployment starts. This is useful if you are using a secret store service like Infisical or AWS Secrets Manager to store your secrets.
+
+`syncEnvVars` takes an async callback function, and any env vars returned from the callback will be synced to Trigger.dev.
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  build: {
+    extensions: [
+      syncEnvVars(async (ctx) => {
+        return [
+          { name: "SECRET_KEY", value: "secret-value" },
+          { name: "ANOTHER_SECRET", value: "another-secret-value" },
+        ];
+      }),
+    ],
+  },
+});
+```
+
+The callback is passed a context object with the following properties:
+
+- `environment`: The environment name that the task is being deployed to (e.g. `production`, `staging`, etc.)
+- `projectRef`: The project ref of the Trigger.dev project
+- `env`: The environment variables that are currently set in the Trigger.dev project
+
+### Example: Sync env vars from Infisical
+
+In this example we're using env vars from [Infisical](https://infisical.com).
+
+```ts trigger.config.ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncEnvVars } from "@trigger.dev/build/extensions/core";
+import { InfisicalSDK } from "@infisical/sdk";
+
+export default defineConfig({
+  build: {
+    extensions: [
+      syncEnvVars(async (ctx) => {
+        const client = new InfisicalSDK();
+
+        await client.auth().universalAuth.login({
+          clientId: process.env.INFISICAL_CLIENT_ID!,
+          clientSecret: process.env.INFISICAL_CLIENT_SECRET!,
+        });
+
+        const { secrets } = await client.secrets().listSecrets({
+          environment: ctx.environment,
+          projectId: process.env.INFISICAL_PROJECT_ID!,
+        });
+
+        return secrets.map((secret) => ({
+          name: secret.secretKey,
+          value: secret.secretValue,
+        }));
+      }),
+    ],
+  },
+});
+```
+
+### syncVercelEnvVars
+
+The `syncVercelEnvVars` build extension syncs environment variables from your Vercel project to Trigger.dev.
+
+<AccordionGroup>
+<Accordion title="Setting up authentication including team projects">
+You need to set the `VERCEL_ACCESS_TOKEN` and `VERCEL_PROJECT_ID` environment variables, or pass
+in the token and project ID as arguments to the `syncVercelEnvVars` build extension. If you're
+working with a team project, you'll also need to set `VERCEL_TEAM_ID`, which can be found in your
+team settings.
+
+You can find / generate the `VERCEL_ACCESS_TOKEN` in your Vercel
+[dashboard](https://vercel.com/account/settings/tokens). Make sure the scope of the token covers
+the project with the environment variables you want to sync.
+</Accordion>
+
+<Accordion title="Running in Vercel build environment">
+When running the build from a Vercel build environment (e.g., during a Vercel deployment), the
+environment variable values will be read from `process.env` instead of fetching them from the
+Vercel API. This is determined by checking if the `VERCEL` environment variable is present.
+
+The API is still used to determine which environment variables are configured for your project, but
+the actual values come from the local environment. Reading values from `process.env` allows the
+extension to use values that Vercel integrations (such as the Neon integration) set per preview
+deployment in the "Provisioning Integrations" phase that happens just before the Vercel build
+starts.
+</Accordion>
+
+<Accordion title="Using with Neon database Vercel integration">
+If you have the Neon database Vercel integration installed and are running builds outside of the
+Vercel environment, we recommend using `syncNeonEnvVars` in addition to `syncVercelEnvVars` for your
+database environment variables.
+
+This ensures that the correct database connection strings are used for your 
+selected environment and current branch, as `syncVercelEnvVars` may not accurately reflect
+branch-specific database credentials when run locally.
+</Accordion>
+</AccordionGroup>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    // This will automatically use the VERCEL_ACCESS_TOKEN and VERCEL_PROJECT_ID environment variables
+    extensions: [syncVercelEnvVars()],
+  },
+});
+```
+
+Or you can pass in the token and project ID as arguments:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncVercelEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      syncVercelEnvVars({
+        projectId: "your-vercel-project-id",
+        vercelAccessToken: "your-vercel-access-token", // optional, we recommend to keep it as env variable
+        vercelTeamId: "your-vercel-team-id", // optional
+      }),
+    ],
+  },
+});
+```
+
+### syncNeonEnvVars
+
+The `syncNeonEnvVars` build extension syncs environment variables from your Neon database project to Trigger.dev. It automatically detects branches and builds the appropriate database connection strings for your environment.
+
+<AccordionGroup>
+<Accordion title="Setting up authentication">
+You need to set the `NEON_ACCESS_TOKEN` and `NEON_PROJECT_ID` environment variables, or pass them
+as arguments to the `syncNeonEnvVars` build extension.
+
+You can generate a `NEON_ACCESS_TOKEN` in your Neon [dashboard](https://console.neon.tech/app/settings/api-keys).
+</Accordion>
+
+<Accordion title="Running in Vercel environment">
+When running the build from a Vercel environment (determined by checking if the `VERCEL`
+environment variable is present), this extension is skipped entirely.
+
+This is because Neon's Vercel integration already handles environment variable synchronization in Vercel environments.
+</Accordion>
+
+<Accordion title="Using with Neon database Vercel integration">
+If you have the Neon database Vercel integration installed and are running builds outside of the
+Vercel environment, we recommend using `syncNeonEnvVars` in addition to `syncVercelEnvVars` for your
+database environment variables.
+
+This ensures that the correct database connection strings are used for your selected environment and current branch, as `syncVercelEnvVars` may not accurately reflect branch-specific database credentials when run locally.
+</Accordion>
+</AccordionGroup>
+
+<Note>
+  This extension is skipped for `prod` environments. It is designed to sync branch-specific
+  database connections for preview/staging environments.
+</Note>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncNeonEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    // This will automatically use the NEON_ACCESS_TOKEN and NEON_PROJECT_ID environment variables
+    extensions: [syncNeonEnvVars()],
+  },
+});
+```
+
+Or you can pass in the token and project ID as arguments:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncNeonEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      syncNeonEnvVars({
+        projectId: "your-neon-project-id",
+        neonAccessToken: "your-neon-access-token", // optional, we recommend to keep it as env variable
+        branch: "your-branch-name", // optional, defaults to ctx.branch
+        databaseName: "your-database-name", // optional, defaults to the first database
+        roleName: "your-role-name", // optional, defaults to the database owner
+        envVarPrefix: "MY_PREFIX_", // optional, prefix for all synced env vars
+      }),
+    ],
+  },
+});
+```
+
+The extension syncs the following environment variables (with optional prefix):
+
+- `DATABASE_URL` - Pooled connection string
+- `DATABASE_URL_UNPOOLED` - Direct connection string
+- `POSTGRES_URL`, `POSTGRES_URL_NO_SSL`, `POSTGRES_URL_NON_POOLING`
+- `POSTGRES_PRISMA_URL` - Connection string optimized for Prisma
+- `POSTGRES_HOST`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DATABASE`
+- `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`
+
+### syncSupabaseEnvVars
+
+The `syncSupabaseEnvVars` build extension syncs environment variables from your Supabase project to Trigger.dev. It uses [Supabase Branching](https://supabase.com/docs/guides/deployment/branching) to automatically detect branches and build the appropriate database connection strings and API keys for your environment.
+
+<AccordionGroup>
+<Accordion title="Setting up authentication">
+You need to set the `SUPABASE_ACCESS_TOKEN` and `SUPABASE_PROJECT_ID` environment variables, or pass them
+as arguments to the `syncSupabaseEnvVars` build extension.
+
+You can generate a `SUPABASE_ACCESS_TOKEN` in your Supabase [dashboard](https://supabase.com/dashboard/account/tokens).
+</Accordion>
+
+<Accordion title="Running in Vercel environment">
+When running the build from a Vercel environment (determined by checking if the `VERCEL`
+environment variable is present), this extension is skipped entirely.
+</Accordion>
+</AccordionGroup>
+
+<Note>
+  For `prod` environments, this extension uses credentials from your default Supabase
+  branch. For `preview` and `staging` environments, it matches the git branch name to a Supabase
+  branch and syncs the corresponding database connection strings and API keys. `dev` environments are skipped.
+</Note>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncSupabaseEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    // This will automatically use the SUPABASE_ACCESS_TOKEN and SUPABASE_PROJECT_ID environment variables
+    extensions: [syncSupabaseEnvVars()],
+  },
+});
+```
+
+Or you can pass in the token, project ID, and other options as arguments:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { syncSupabaseEnvVars } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      syncSupabaseEnvVars({
+        projectId: "your-supabase-project-id",
+        supabaseAccessToken: "your-supabase-access-token", // optional, we recommend to keep it as env variable
+        branch: "your-branch-name", // optional, defaults to ctx.branch
+        envVarPrefix: "MY_PREFIX_", // optional, prefix for all synced env vars
+      }),
+    ],
+  },
+});
+```
+
+The extension syncs the following environment variables (with optional prefix):
+
+- `DATABASE_URL`, `POSTGRES_URL`, `SUPABASE_DB_URL` — PostgreSQL connection strings
+- `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE` — Individual connection parameters
+- `SUPABASE_URL` — Supabase API URL
+- `SUPABASE_ANON_KEY` — Anonymous API key
+- `SUPABASE_SERVICE_ROLE_KEY` — Service role API key
+- `SUPABASE_JWT_SECRET` — JWT secret