Skip to content

Commit 3772b5a

Browse files
ericallamericallam
authored
New Doc: create your own build extension reference (#1347)
* Build extension guide WIP * Create your own build extension guide
1 parent d7a65f3 commit 3772b5a

File tree

6 files changed

+433
-22
lines changed

6 files changed

+433
-22
lines changed

‎docs/config/config-file.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "The trigger.config.ts file"
3-
sidebarTitle: "Configuration"
3+
sidebarTitle: "trigger.config.ts"
44
description: "This file is used to configure your project and how it's built."
55
---
66

‎docs/config/extensions/custom.mdx

Whitespace-only changes.

‎docs/config/extensions/esbuild-plugins.mdx

Whitespace-only changes.

‎docs/config/extensions/overview.mdx

Lines changed: 377 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,379 @@
11
---
2-
title: "Overview"
3-
sidebarTitle: "Overview"
4-
description: "This file is used to configure your project and how it's bundled."
2+
title: "Build extensions"
3+
description: "Customize how your project is built and deployed to Trigger.dev with build extensions"
54
---
5+
6+
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:
7+
8+
- Add additional files to the build
9+
- Add dependencies to the list of externals
10+
- Add esbuild plugins
11+
- Add additional npm dependencies
12+
- Add additional system packages to the image build container
13+
- Add commands to run in the image build container
14+
- Add environment variables to the image build container
15+
- Sync environment variables to your Trigger.dev project
16+
17+
## Creating a build extension
18+
19+
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:
20+
21+
```ts
22+
import { defineConfig } from "@trigger.dev/sdk/v3";
23+
24+
export default defineConfig({
25+
project: "my-project",
26+
build: {
27+
extensions: [
28+
{
29+
name: "my-extension",
30+
onBuildStart: async (context) => {
31+
console.log("Build starting!");
32+
},
33+
},
34+
],
35+
},
36+
});
37+
```
38+
39+
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:
40+
41+
<Note>
42+
You'll need to add the `@trigger.dev/build` package to your `devDependencies` before the below
43+
code will work. Make sure it's version matches that of the installed `@trigger.dev/sdk` package.
44+
</Note>
45+
46+
```ts
47+
import { defineConfig } from "@trigger.dev/sdk/v3";
48+
import { BuildExtension } from "@trigger.dev/build";
49+
50+
export default defineConfig({
51+
project: "my-project",
52+
build: {
53+
extensions: [myExtension()],
54+
},
55+
});
56+
57+
function myExtension(): BuildExtension {
58+
return {
59+
name: "my-extension",
60+
onBuildStart: async (context) => {
61+
console.log("Build starting!");
62+
},
63+
};
64+
}
65+
```
66+
67+
## Build hooks
68+
69+
### externalsForTarget
70+
71+
This allows the extension to add additional dependencies to the list of externals for the build. This is useful for dependencies that are not included in the bundle, but are expected to be available at runtime.
72+
73+
```ts
74+
import { defineConfig } from "@trigger.dev/sdk/v3";
75+
76+
export default defineConfig({
77+
project: "my-project",
78+
build: {
79+
extensions: [
80+
{
81+
name: "my-extension",
82+
externalsForTarget: async (target) => {
83+
return ["my-dependency"];
84+
},
85+
},
86+
],
87+
},
88+
});
89+
```
90+
91+
### onBuildStart
92+
93+
This hook runs before the build starts. It receives the `BuildContext` object as an argument.
94+
95+
```ts
96+
import { defineConfig } from "@trigger.dev/sdk/v3";
97+
98+
export default defineConfig({
99+
project: "my-project",
100+
build: {
101+
extensions: [
102+
{
103+
name: "my-extension",
104+
onBuildStart: async (context) => {
105+
console.log("Build starting!");
106+
},
107+
},
108+
],
109+
},
110+
});
111+
```
112+
113+
If you want to add an esbuild plugin, you must do so in the `onBuildStart` hook. Here's an example of adding a custom esbuild plugin:
114+
115+
```ts
116+
import { defineConfig } from "@trigger.dev/sdk/v3";
117+
118+
export default defineConfig({
119+
project: "my-project",
120+
build: {
121+
extensions: [
122+
{
123+
name: "my-extension",
124+
onBuildStart: async (context) => {
125+
context.registerPlugin({
126+
name: "my-plugin",
127+
setup(build) {
128+
build.onLoad({ filter: /.*/, namespace: "file" }, async (args) => {
129+
return {
130+
contents: "console.log('Hello, world!')",
131+
loader: "js",
132+
};
133+
});
134+
},
135+
});
136+
},
137+
},
138+
],
139+
},
140+
});
141+
```
142+
143+
You can use the `BuildContext.target` property to determine if the build is for `dev` or `deploy`:
144+
145+
```ts
146+
import { defineConfig } from "@trigger.dev/sdk/v3";
147+
148+
export default defineConfig({
149+
project: "my-project",
150+
build: {
151+
extensions: [
152+
{
153+
name: "my-extension",
154+
onBuildStart: async (context) => {
155+
if (context.target === "dev") {
156+
console.log("Building for dev");
157+
} else {
158+
console.log("Building for deploy");
159+
}
160+
},
161+
},
162+
],
163+
},
164+
});
165+
```
166+
167+
### onBuildComplete
168+
169+
This hook runs after the build completes. It receives the `BuildContext` object and a `BuildManifest` object as arguments. This is where you can add in one or more `BuildLayer`'s to the context.
170+
171+
```ts
172+
import { defineConfig } from "@trigger.dev/sdk/v3";
173+
174+
export default defineConfig({
175+
project: "my-project",
176+
build: {
177+
extensions: [
178+
{
179+
name: "my-extension",
180+
onBuildComplete: async (context, manifest) => {
181+
context.addLayer({
182+
id: "more-dependencies",
183+
dependencies,
184+
});
185+
},
186+
},
187+
],
188+
},
189+
});
190+
```
191+
192+
See the [addLayer](#addlayer) documentation for more information on how to use `addLayer`.
193+
194+
## BuildTarget
195+
196+
Can either be `dev` or `deploy`, matching the CLI command name that is being run.
197+
198+
```sh
199+
npx trigger.dev@latest dev # BuildTarget is "dev"
200+
npx trigger.dev@latest deploy # BuildTarget is "deploy"
201+
```
202+
203+
## BuildContext
204+
205+
### addLayer()
206+
207+
<ParamField path="layer" type="BuildLayer">
208+
The layer to add to the build context. See the [BuildLayer](#buildlayer) documentation for more
209+
information.
210+
</ParamField>
211+
212+
### registerPlugin()
213+
214+
<ParamField path="plugin" type="esbuild.Plugin" required>
215+
The esbuild plugin to register.
216+
</ParamField>
217+
218+
<ParamField path="options" type="object">
219+
<Expandable title="properties">
220+
<ResponseField name="target" type="BuildTarget">
221+
An optional target to register the plugin for. If not provided, the plugin will be registered
222+
for all targets.
223+
</ResponseField>
224+
<ResponseField name="placement" type="first | last">
225+
An optional placement for the plugin. If not provided, the plugin will be registered in place.
226+
This allows you to control the order of plugins.
227+
</ResponseField>
228+
</Expandable>
229+
</ParamField>
230+
231+
### resolvePath()
232+
233+
Resolves a path relative to the project's working directory.
234+
235+
<ParamField path="path" type="string">
236+
The path to resolve.
237+
</ParamField>
238+
239+
```ts
240+
const resolvedPath = context.resolvePath("my-other-dependency");
241+
```
242+
243+
### properties
244+
245+
<ParamField path="target" type="BuildTarget">
246+
The target of the build, either `dev` or `deploy`.
247+
</ParamField>
248+
249+
<ParamField path="config" type="ResolvedConfig">
250+
<Expandable title="properties">
251+
<ResponseField name="runtime" type="string">
252+
The runtime of the project (either node or bun)
253+
</ResponseField>
254+
<ResponseField name="project" type="string">
255+
The project ref
256+
</ResponseField>
257+
<ResponseField name="dirs" type="string[]">
258+
The trigger directories to search for tasks
259+
</ResponseField>
260+
<ResponseField name="build" type="object">
261+
The build configuration object
262+
</ResponseField>
263+
<ResponseField name="workingDir" type="string">
264+
The working directory of the project
265+
</ResponseField>
266+
<ResponseField name="workspaceDir" type="string">
267+
The root workspace directory of the project
268+
</ResponseField>
269+
<ResponseField name="packageJsonPath" type="string">
270+
The path to the package.json file
271+
</ResponseField>
272+
<ResponseField name="lockfilePath" type="string">
273+
The path to the lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml)
274+
</ResponseField>
275+
<ResponseField name="configFile" type="string">
276+
The path to the trigger.config.ts file
277+
</ResponseField>
278+
<ResponseField name="tsconfigPath" type="string">
279+
The path to the tsconfig.json file
280+
</ResponseField>
281+
</Expandable>
282+
</ParamField>
283+
284+
<ParamField path="logger" type="BuildLogger">
285+
A logger object that can be used to log messages to the console.
286+
</ParamField>
287+
288+
## BuildLayer
289+
290+
<ParamField path="id" type="string">
291+
A unique identifier for the layer.
292+
</ParamField>
293+
294+
<ParamField path="commands" type="string[]">
295+
An array of commands to run in the image build container.
296+
297+
```ts
298+
commands: ["echo 'Hello, world!'"];
299+
```
300+
301+
These commands are run after packages have been installed and the code copied into the container in the "build" stage of the Dockerfile. This means you cannot install system packages in these commands because they won't be available in the final stage. To do that, please use the `pkgs` property of the `image` object.
302+
303+
</ParamField>
304+
305+
<ParamField path="image" type="object">
306+
<Expandable title="properties">
307+
<ResponseField name="pkgs" type="string[]">
308+
An array of system packages to install in the image build container.
309+
</ResponseField>
310+
<ResponseField name="instructions" type="string[]">
311+
An array of instructions to add to the Dockerfile.
312+
</ResponseField>
313+
</Expandable>
314+
</ParamField>
315+
316+
<ParamField path="build" type="object">
317+
<Expandable title="properties">
318+
<ResponseField name="env" type="Record<string, string>">
319+
Environment variables to add to the image build container, but only during the "build" stage
320+
of the Dockerfile. This is where you'd put environment variables that are needed when running
321+
any of the commands in the `commands` array.
322+
</ResponseField>
323+
</Expandable>
324+
</ParamField>
325+
326+
<ParamField path="deploy" type="object">
327+
<Expandable title="properties">
328+
<ResponseField name="env" type="Record<string, string>">
329+
Environment variables that should sync to the Trigger.dev project, which will then be avalable
330+
in your tasks at runtime. Importantly, these are NOT added to the image build container, but
331+
are instead added to the Trigger.dev project and stored securely.
332+
</ResponseField>
333+
</Expandable>
334+
</ParamField>
335+
336+
<ParamField path="dependencies" type="Record<string, string>">
337+
An object of dependencies to add to the build. The key is the package name and the value is the
338+
version.
339+
340+
```ts
341+
dependencies: {
342+
"my-dependency": "^1.0.0",
343+
};
344+
```
345+
346+
</ParamField>
347+
348+
### examples
349+
350+
Add a command that will echo the value of an environment variable:
351+
352+
```ts
353+
context.addLayer({
354+
id: "my-layer",
355+
commands: [`echo $MY_ENV_VAR`],
356+
build: {
357+
env: {
358+
MY_ENV_VAR: "Hello, world!",
359+
},
360+
},
361+
});
362+
```
363+
364+
## Troubleshooting
365+
366+
When creating a build extension, you may run into issues with the build process. One thing that can help is turning on `debug` logging when running either `dev` or `deploy`:
367+
368+
```sh
369+
npx trigger.dev@latest dev --log-level debug
370+
npx trigger.dev@latest deploy --log-level debug
371+
```
372+
373+
Another helpful tool is the `--dry-run` flag on the `deploy` command, which will bundle your project and generate the Containerfile (e.g. the Dockerfile) without actually deploying it. This can help you see what the final image will look like and debug any issues with the build process.
374+
375+
```sh
376+
npx trigger.dev@latest deploy --dry-run
377+
```
378+
379+
You should also take a look at our built in extensions for inspiration on how to create your own. You can find them in in [the source code here](https://github.com/triggerdotdev/trigger.dev/tree/main/packages/build/src/extensions).

‎docs/config/extensions/prisma.mdx

Lines changed: 0 additions & 5 deletions
This file was deleted.

0 commit comments

Comments
 (0)