Build extension guide WIP

Author: ericallam

docs/config/config-file.mdx

@@ -1,6 +1,6 @@
 ---
 title: "The trigger.config.ts file"
-sidebarTitle: "Configuration"
+sidebarTitle: "trigger.config.ts"
 description: "This file is used to configure your project and how it's built."
 ---
 

docs/config/extensions/custom.mdx

@@ -1,5 +1,80 @@
 ---
-title: "Overview"
-sidebarTitle: "Overview"
-description: "This file is used to configure your project and how it's bundled."
+title: "Build extensions"
+description: "Customize how your project is built and deployed to Trigger.dev with build extensions"
 ---
+
+Build extension 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). See our [trigger.config.ts reference](/config/config-file#extensions) for more information on how to install and use our built-in extensions. Build extensions can do the following:
+
+- Add additional files to the build
+- Add esbuild plugins
+- Add additional npm dependencies
+- Add additional system packages to the image build container
+- Add commands to run in the image build container
+- Add environment variables to the image build container
+- Sync environment variables to your Trigger.dev project
+
+## Creating a build extension
+
+Build extensions are added to your `trigger.config.ts` file, with a required `name` and optional build hook functions. Here's a simple example of a build extension that just logs a message when the build starts:
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk/v3";
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [
+      {
+        name: "my-extension",
+        onBuildStart: async (context) => {
+          console.log("Build starting!");
+        },
+      },
+    ],
+  },
+});
+```
+
+You can also extract that out into a function instead of defining it inline, in which case you will need to import the `BuildExtension` type from the `@trigger.dev/build` package:
+
+<Note>
+  You'll need to add the `@trigger.dev/build` package to your `devDependencies` before the below
+  code will work. Make sure it's version matches that of the installed `@trigger.dev/sdk` package.
+</Note>
+
+```ts
+import { defineConfig } from "@trigger.dev/sdk/v3";
+import { BuildExtension } from "@trigger.dev/build";
+
+export default defineConfig({
+  project: "my-project",
+  build: {
+    extensions: [myExtension()],
+  },
+});
+
+function myExtension(): BuildExtension {
+  return {
+    name: "my-extension",
+    onBuildStart: async (context) => {
+      console.log("Build starting!");
+    },
+  };
+}
+```
+
+## Build hooks
+
+### onBuildStart
+
+### onBuildComplete
+
+## Reference
+
+### BuildContext
+
+### BuildLayer
+
+## Troubleshooting
+
+Describe how to use --dry-run

docs/config/extensions/esbuild-plugins.mdx

@@ -1,7 +1,10 @@
 {
   "$schema": "https://mintlify.com/schema.json",
   "name": "Trigger.dev",
-  "openapi": ["/openapi.yml", "/v3-openapi.yaml"],
+  "openapi": [
+    "/openapi.yml",
+    "/v3-openapi.yaml"
+  ],
   "api": {
     "playground": {
       "mode": "simple"
@@ -100,23 +103,41 @@
   "navigation": [
     {
       "group": "Getting Started",
-      "pages": ["introduction", "quick-start", "how-it-works", "upgrading-beta", "limits"]
+      "pages": [
+        "introduction",
+        "quick-start",
+        "how-it-works",
+        "upgrading-beta",
+        "limits"
+      ]
     },
     {
       "group": "Fundamentals",
       "pages": [
         {
           "group": "Tasks",
-          "pages": ["tasks/overview", "tasks/scheduled"]
+          "pages": [
+            "tasks/overview",
+            "tasks/scheduled"
+          ]
         },
         "triggering",
         "apikeys",
-        "config/config-file"
+        {
+          "group": "Configuration",
+          "pages": [
+            "config/config-file",
+            "config/extensions/overview"
+          ]
+        }
       ]
     },
     {
       "group": "Development",
-      "pages": ["cli-dev", "run-tests"]
+      "pages": [
+        "cli-dev",
+        "run-tests"
+      ]
     },
     {
       "group": "Deployment",
@@ -126,7 +147,9 @@
         "github-actions",
         {
           "group": "Deployment integrations",
-          "pages": ["vercel-integration"]
+          "pages": [
+            "vercel-integration"
+          ]
         }
       ]
     },
@@ -138,7 +161,13 @@
         "errors-retrying",
         {
           "group": "Wait",
-          "pages": ["wait", "wait-for", "wait-until", "wait-for-event", "wait-for-request"]
+          "pages": [
+            "wait",
+            "wait-for",
+            "wait-until",
+            "wait-for-event",
+            "wait-for-request"
+          ]
         },
         "queue-concurrency",
         "versioning",
@@ -156,7 +185,10 @@
         "management/overview",
         {
           "group": "Tasks API",
-          "pages": ["management/tasks/trigger", "management/tasks/batch-trigger"]
+          "pages": [
+            "management/tasks/trigger",
+            "management/tasks/batch-trigger"
+          ]
         },
         {
           "group": "Runs API",
@@ -194,7 +226,9 @@
         },
         {
           "group": "Projects API",
-          "pages": ["management/projects/runs"]
+          "pages": [
+            "management/projects/runs"
+          ]
         }
       ]
     },
@@ -240,7 +274,11 @@
     },
     {
       "group": "Help",
-      "pages": ["community", "help-slack", "help-email"]
+      "pages": [
+        "community",
+        "help-slack",
+        "help-email"
+      ]
     },
     {
       "group": "Frameworks",
@@ -264,11 +302,15 @@
     },
     {
       "group": "Dashboard",
-      "pages": ["guides/dashboard/creating-a-project"]
+      "pages": [
+        "guides/dashboard/creating-a-project"
+      ]
     },
     {
       "group": "Migrations",
-      "pages": ["guides/use-cases/upgrading-from-v2"]
+      "pages": [
+        "guides/use-cases/upgrading-from-v2"
+      ]
     },
     {
       "group": "Examples",
@@ -290,4 +332,4 @@
     "github": "https://github.com/triggerdotdev",
     "linkedin": "https://www.linkedin.com/company/triggerdotdev"
   }
-}
+}