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

package/docs/config/extensions/overview.mdx

@@ -0,0 +1,67 @@
+---
+title: "Build extensions"
+sidebarTitle: "Overview"
+description: "Customize how your project is built and deployed to Trigger.dev with build extensions"
+---
+
+Build extensions allow you to hook into the build system and customize the build process or the resulting bundle and container image (in the case of deploying).
+
+You can use pre-built extensions by installing the `@trigger.dev/build` package into your `devDependencies`, or you can create your own.
+
+Build extensions are added to your `trigger.config.ts` file under the `build.extensions` property:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [
+      {
+        name: "my-extension",
+        onBuildStart: async (context) => {
+          console.log("Build starting!");
+        },
+      },
+    ],
+  },
+});
+```
+
+If you are using a pre-built extension, you can import it from the `@trigger.dev/build` package:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { ffmpeg } from "@trigger.dev/build/extensions/core";
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [ffmpeg()],
+  },
+});
+```
+
+## Built-in extensions
+
+Trigger.dev provides a set of built-in extensions that you can use to customize how your project is built and deployed. These extensions are available out of the box and can be configured in your `trigger.config.ts` file.
+
+| Extension                                                             | Description                                                                    |
+| :-------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
+| [prismaExtension](/config/extensions/prismaExtension)                 | Using prisma in your Trigger.dev tasks                                         |
+| [pythonExtension](/config/extensions/pythonExtension)                 | Execute Python scripts in your project                                         |
+| [puppeteer](/config/extensions/puppeteer)                             | Use Puppeteer in your Trigger.dev tasks                                        |
+| [ffmpeg](/config/extensions/ffmpeg)                                   | Use FFmpeg in your Trigger.dev tasks                                           |
+| [aptGet](/config/extensions/aptGet)                                   | Install system packages in your build image                                    |
+| [additionalFiles](/config/extensions/additionalFiles)                 | Copy additional files to your build image                                      |
+| [additionalPackages](/config/extensions/additionalPackages)           | Install additional npm packages in your build image                            |
+| [syncEnvVars](/config/extensions/syncEnvVars)                         | Automatically sync environment variables from external services to Trigger.dev |
+| [syncVercelEnvVars](/config/extensions/syncEnvVars#syncVercelEnvVars) | Automatically sync environment variables from Vercel to Trigger.dev            |
+| [syncSupabaseEnvVars](/config/extensions/syncEnvVars#syncSupabaseEnvVars) | Automatically sync environment variables from Supabase to Trigger.dev          |
+| [esbuildPlugin](/config/extensions/esbuildPlugin)                     | Add existing or custom esbuild extensions to customize your build process      |
+| [emitDecoratorMetadata](/config/extensions/emitDecoratorMetadata)     | Enable `emitDecoratorMetadata` in your TypeScript build                        |
+| [audioWaveform](/config/extensions/audioWaveform)                     | Add Audio Waveform to your build image                                         |
+
+## Custom extensions
+
+If one of the built-in extensions doesn't meet your needs, you can create your own custom extension. See our [guide on creating custom build extensions](/config/extensions/custom) for more information.

package/docs/config/extensions/playwright.mdx

@@ -0,0 +1,195 @@
+---
+title: "Playwright"
+sidebarTitle: "playwright"
+description: "Use the playwright build extension to use Playwright with Trigger.dev"
+---
+
+If you are using [Playwright](https://playwright.dev/), you should use the Playwright build extension.
+
+- Automatically installs Playwright and required browser dependencies
+- Allows you to specify which browsers to install (chromium, firefox, webkit)
+- Supports headless or non-headless mode
+- Lets you specify the Playwright version, or auto-detects it
+- Installs only the dependencies needed for the selected browsers to optimize build time and image size
+
+<Note>
+  This extension only affects the build and deploy process, not the `dev` command.
+</Note>
+
+You can use it for a simple Playwright setup like this:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+export default defineConfig({
+  project: "<project ref>",
+  // Your other config settings...
+  build: {
+    extensions: [
+      playwright(),
+    ],
+  },
+});
+```
+
+### Options
+
+- `browsers`: Array of browsers to install. Valid values: `"chromium"`, `"firefox"`, `"webkit"`. Default: `["chromium"]`.
+- `headless`: Run browsers in headless mode. Default: `true`. If set to `false`, a virtual display (Xvfb) will be set up automatically.
+- `version`: Playwright version to install. If not provided, the version will be auto-detected from your dependencies (recommended).
+
+  <Warning>
+    Using a different version in your app than specified here will break things. We recommend not setting this option to automatically detect the version.
+  </Warning>
+
+### Custom browsers and version
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      playwright({
+        browsers: ["chromium", "webkit"], // optional, will use ["chromium"] if not provided
+        version: "1.43.1",  // optional, will automatically detect the version if not provided
+      }),
+    ],
+  },
+});
+```
+
+### Headless mode
+
+By default, browsers are run in headless mode. If you need to run browsers with a UI (for example, for debugging), set `headless: false`. This will automatically set up a virtual display using Xvfb.
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      playwright({
+        headless: false,
+      }),
+    ],
+  },
+});
+```
+
+### Environment variables
+
+The extension sets the following environment variables during the build:
+
+- `PLAYWRIGHT_BROWSERS_PATH`: Set to `/ms-playwright` so Playwright finds the installed browsers
+- `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD`: Set to `1` to skip browser download at runtime
+- `PLAYWRIGHT_SKIP_BROWSER_VALIDATION`: Set to `1` to skip browser validation at runtime
+- `DISPLAY`: Set to `:99` if `headless: false` (for Xvfb)
+
+## Troubleshooting
+
+### Browser download failures
+
+If you encounter errors during the build process related to browser downloads (e.g., "failed to solve: process did not complete successfully: exit code: 9"), this is a known issue with certain Playwright versions.
+
+**Workaround:** Revert Playwright to version `1.40.0` in your project dependencies. You can specify this version explicitly in your config:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk";
+import { playwright } from "@trigger.dev/build/extensions/playwright";
+
+export default defineConfig({
+  project: "<project ref>",
+  build: {
+    extensions: [
+      playwright({
+        version: "1.40.0",
+      }),
+    ],
+  },
+});
+```
+
+For more details, see [GitHub issue #2440](https://github.com/triggerdotdev/trigger.dev/issues/2440#issuecomment-3815104376).
+
+## Managing browser instances
+
+To prevent issues with waits and resumes, you can use middleware and locals to manage the browser instance. This will ensure the browser is available for the whole run, and is properly cleaned up on waits, resumes, and after the run completes.
+
+Here's an example using `chromium`, but you can adapt it for other browsers:
+
+```ts
+import { logger, tasks, locals } from "@trigger.dev/sdk";
+import { chromium, type Browser } from "playwright";
+
+// Create a locals key for the browser instance
+const PlaywrightBrowserLocal = locals.create<{ browser: Browser }>("playwright-browser");
+
+export function getBrowser() {
+  return locals.getOrThrow(PlaywrightBrowserLocal).browser;
+}
+
+export function setBrowser(browser: Browser) {
+  locals.set(PlaywrightBrowserLocal, { browser });
+}
+
+tasks.middleware("playwright-browser", async ({ next }) => {
+  // Launch the browser before the task runs
+  const browser = await chromium.launch();
+  setBrowser(browser);
+  logger.log("[chromium]: Browser launched (middleware)");
+
+  try {
+    await next();
+  } finally {
+    // Always close the browser after the task completes
+    await browser.close();
+    logger.log("[chromium]: Browser closed (middleware)");
+  }
+});
+
+tasks.onWait("playwright-browser", async () => {
+  // Close the browser when the run is waiting
+  const browser = getBrowser();
+  await browser.close();
+  logger.log("[chromium]: Browser closed (onWait)");
+});
+
+tasks.onResume("playwright-browser", async () => {
+  // Relaunch the browser when the run resumes
+  // Note: You will have to have to manually get a new browser instance in the run function
+  const browser = await chromium.launch();
+  setBrowser(browser);
+  logger.log("[chromium]: Browser launched (onResume)");
+});
+```
+
+You can then use `getBrowser()` in your task's `run` function to access the browser instance:
+
+```ts
+export const playwrightTestTask = task({
+  id: "playwright-test",
+  run: async () => {
+    const browser = getBrowser();
+    const page = await browser.newPage();
+    await page.goto("https://google.com");
+    await page.screenshot({ path: "screenshot.png" });
+    await page.close();
+
+    // Waits will gracefully close the browser
+    await wait.for({ seconds: 10 });
+
+    // On resume, we will re-launch the browser but you will have to manually get the new instance
+    const newBrowser = getBrowser();
+    const newPage = await newBrowser.newPage();
+    await newPage.goto("https://playwright.dev");
+    await newPage.screenshot({ path: "screenshot2.png" });
+    await newPage.close();
+  },
+});
+```