Skip to content

Commit b5e6033

Browse files
ericallamericallam
committed
Initial guide
1 parent 3fded0a commit b5e6033

File tree

2 files changed

+254
-3
lines changed

2 files changed

+254
-3
lines changed

‎docs/guides/new-build-system-preview.mdx

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
---
2+
title: "Upgrade to new build system"
3+
description: "How to use the new build system preview release"
4+
---
5+
6+
Based on feedback and a steady flow of issues from our previous build system, we're happy to share with you a preview release of our new build system that (hopefully) fixes most of the issues you may have faced.
7+
8+
The main features of the new build sytem are:
9+
10+
- **Bundling by default**: All dependencies are bundled by default, so you no longer need to specify which dependencies to bundle. This solves a whole bunch of issues related to monorepos.
11+
- **Build extensions**: A new way to extend the build process with custom logic. This is a more flexible and powerful way to extend the build process compared to the old system. (including custom esbuild plugin support)
12+
- **Improved configuration**: We've migrated to using [c12](https://github.com/unjs/c12) to power our configuration system.
13+
- **Improved error handling**: We now do a much better job of reporting of any errors that happen during the indexing process by loading your trigger task files dynamically.
14+
- **Improved cold start times**: Previously, we would load all your trigger task files at once, which could lead to long cold start times. Now we load your trigger task files dynamically, which should improve cold start times.
15+
16+
## Update packages
17+
18+
To use the new build system, you have to update to use our preview packages. Update the `@trigger.dev/sdk` package in your package.json:
19+
20+
```json
21+
"@trigger.dev/sdk": "https://pkg.pr.new/triggerdotdev/trigger.dev/@trigger.dev/sdk@3fded0a"
22+
```
23+
24+
You will also need to update your usage of the `trigger.dev` CLI to use the preview release. If you run the CLI via `npx` you can update to the preview release like so:
25+
26+
```sh
27+
# old way
28+
npx trigger.dev@beta dev
29+
30+
# using the preview release
31+
npx https://pkg.pr.new/triggerdotdev/trigger.dev@3fded0a dev
32+
```
33+
34+
If you've added the `trigger.dev` CLI to your `devDependencies`, then you should update the version to point to the preview release:
35+
36+
```json
37+
"trigger.dev": "https://pkg.pr.new/triggerdotdev/trigger.dev@3fded0a"
38+
```
39+
40+
Once you do that make sure you re-install your dependencies using `npm i` or the equivalent with your preferred package manager.
41+
42+
## Update your `trigger.config.ts`
43+
44+
The new build system does not effect your trigger task files at all, so those can remain unchanged. However, you may need to make changes to your `trigger.config.ts` file.
45+
46+
### `defineConfig`
47+
48+
You should now import the `defineConfig` function from `@trigger.dev/sdk/v3` and export the config as the default export:
49+
50+
```
51+
import { defineConfig } from "@trigger.dev/sdk/v3";
52+
53+
export default defineConfig({
54+
project: "<project ref>",
55+
});
56+
```
57+
58+
### Deprecated: `dependenciesToBundle`
59+
60+
The new build system will bundle all dependencies by default, so `dependenciesToBundle` no longer makes any sense and can be removed.
61+
62+
#### Externals
63+
64+
Now that all dependencies are bundled, there are some situations where bundling a dependency doesn't work, and needs to be made external (e.g. when a dependency includes a native module). You can now specify these dependencies as build externals in the `defineConfig` function:
65+
66+
```ts
67+
import { defineConfig } from "@trigger.dev/sdk/v3";
68+
69+
export default defineConfig({
70+
project: "<project ref>",
71+
build: {
72+
externals: ["native-module"],
73+
},
74+
});
75+
```
76+
77+
`externals` is an array of strings, where each string is the name of a dependency that should be made external. Glob expressions are also supported and use the [minimatch](https://github.com/isaacs/minimatch) matcher.
78+
79+
### `additionalFiles`
80+
81+
The `additionalFiles` option has been moved to our new build extension system.
82+
83+
To use build extensions, you'll need to add the `@trigger.dev/build` package to your `devDependencies`:
84+
85+
```sh
86+
npm add https://pkg.pr.new/triggerdotdev/trigger.dev/@trigger.dev/build@3fded0a -D
87+
```
88+
89+
Now you can import the `additionalFiles` build extension and use it in your `trigger.config.ts` file:
90+
91+
```ts
92+
import { defineConfig } from "@trigger.dev/sdk/v3";
93+
import { additionalFiles } from "@trigger.dev/build/extensions/core";
94+
95+
export default defineConfig({
96+
project: "<project ref>",
97+
build: {
98+
extensions: [
99+
additionalFiles({ files: ["wrangler/wrangler.toml", "./assets/**", "./fonts/**"] }),
100+
],
101+
},
102+
});
103+
```
104+
105+
### `additionalPackages`
106+
107+
The `additionalPackages` option has been moved to our new build extension system.
108+
109+
To use build extensions, you'll need to add the `@trigger.dev/build` package to your `devDependencies`:
110+
111+
```sh
112+
npm add https://pkg.pr.new/triggerdotdev/trigger.dev/@trigger.dev/build@3fded0a -D
113+
```
114+
115+
Now you can import the `additionalPackages` build extension and use it in your `trigger.config.ts` file:
116+
117+
```ts
118+
import { defineConfig } from "@trigger.dev/sdk/v3";
119+
import { additionalPackages } from "@trigger.dev/build/extensions/core";
120+
121+
export default defineConfig({
122+
project: "<project ref>",
123+
build: {
124+
extensions: [additionalPackages({ packages: ["wrangler"] })],
125+
},
126+
});
127+
```
128+
129+
### `resolveEnvVars`
130+
131+
The `resolveEnvVars` export has been moved to our new build extension system.
132+
133+
To use build extensions, you'll need to add the `@trigger.dev/build` package to your `devDependencies`:
134+
135+
```sh
136+
npm add https://pkg.pr.new/triggerdotdev/trigger.dev/@trigger.dev/build@3fded0a -D
137+
```
138+
139+
Now you can import the `syncEnvVars` build extension and use it in your `trigger.config.ts` file:
140+
141+
```ts
142+
import { defineConfig } from "@trigger.dev/sdk/v3";
143+
import { syncEnvVars } from "@trigger.dev/build/extensions/core";
144+
145+
export default defineConfig({
146+
project: "<project ref>",
147+
build: {
148+
extensions: [
149+
syncEnvVars(async (params) => {
150+
return {
151+
MY_ENV_VAR: "my-value",
152+
};
153+
}),
154+
],
155+
},
156+
});
157+
```
158+
159+
The `syncEnvVars` callback function works very similarly to the [`resolveEnvVars`](/deploy-environment-variables#sync-env-vars-from-another-service) callback, but now instead of returning an object with a `variables` key that contains the environment variables, you return an object with the environment variables directly (see the example above).
160+
161+
One other difference is now `params.env` only contains the environment variables that are set in the Trigger.dev environment variables, and not the environment variables from the process. If you want to access the environment variables from the process, you can use `process.env`.
162+
163+
### emitDecoratorMetadata
164+
165+
If you make use of decorators in your code, and have enabled the `emitDecoratorMetadata` tsconfig compiler option, you'll need to enable this in the new build sytem using the `emitDecoratorMetadata` build extension:
166+
167+
```ts
168+
import { defineConfig } from "@trigger.dev/sdk/v3";
169+
import { emitDecoratorMetadata } from "@trigger.dev/build/extensions/typescript";
170+
171+
export default defineConfig({
172+
project: "<project ref>",
173+
build: {
174+
extensions: [emitDecoratorMetadata()],
175+
},
176+
});
177+
```
178+
179+
### Prisma
180+
181+
We've created a build extension to support using Prisma in your Trigger.dev tasks. To use this extension, you'll need to add the `@trigger.dev/build` package to your `devDependencies`:
182+
183+
```sh
184+
npm add https://pkg.pr.new/triggerdotdev/trigger.dev/@trigger.dev/build@3fded0a -D
185+
```
186+
187+
Then you can import the `prismaExtension` build extension and use it in your `trigger.config.ts` file, passing in the path to your Prisma schema file:
188+
189+
```ts
190+
import { defineConfig } from "@trigger.dev/sdk/v3";
191+
import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
192+
193+
export default defineConfig({
194+
project: "<project ref>",
195+
build: {
196+
extensions: [
197+
prismaExtension({
198+
schema: "prisma/schema.prisma",
199+
}),
200+
],
201+
},
202+
});
203+
```
204+
205+
This will make sure that your prisma client is generated during the build process when deploying to Trigger.dev.
206+
207+
<Note>
208+
This does not have any effect when running the `dev` command, so you'll need to make sure you
209+
generate your client locally first.
210+
</Note>
211+
212+
If you want to also run migrations during the build process, you can pass in the `migrate` option:
213+
214+
```ts
215+
import { defineConfig } from "@trigger.dev/sdk/v3";
216+
import { prismaExtension } from "@trigger.dev/build/extensions/prisma";
217+
218+
export default defineConfig({
219+
project: "<project ref>",
220+
build: {
221+
extensions: [
222+
prismaExtension({
223+
schema: "prisma/schema.prisma",
224+
migrate: true,
225+
directUrlEnvVarName: "DATABASE_URL_UNPOOLED", // optional - the name of the environment variable that contains the direct database URL if you are using a direct database URL
226+
}),
227+
],
228+
},
229+
});
230+
```
231+
232+
### audioWaveform
233+
234+
Previously, we installed [Audio Waveform](https://github.com/bbc/audiowaveform) in the build image. That's been moved to a build extension:
235+
236+
```ts
237+
import { defineConfig } from "@trigger.dev/sdk/v3";
238+
import { audioWaveform } from "@trigger.dev/build/extensions/audioWaveform";
239+
240+
export default defineConfig({
241+
project: "<project ref>",
242+
build: {
243+
extensions: [audioWaveform()], // uses verson 1.1.0 of audiowaveform by default
244+
},
245+
});
246+
```
247+
248+
## Known issues
249+
250+
- Path aliases are not yet support in your `trigger.config.ts` file. To workaround this issue you'll need to rewrite path aliases to their relative paths. (See [this](https://github.com/unjs/jiti/issues/166) and [this](https://knip.dev/reference/known-issues#path-aliases-in-config-files)) for more info.
251+
- Some events in the run trace view may get permanently stuck in a loading state. This is a known issue and we're working on a fix.

‎packages/cli-v3/src/config.ts

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ function validateConfig(config: TriggerConfig, warn = true) {
213213
if (config.additionalFiles && config.additionalFiles.length > 0) {
214214
warn &&
215215
prettyWarning(
216-
`The "additionalFiles" option is deprecated and will be removed. Use the "additionalFiles" build extension instead. See https://trigger.dev/docs/trigger-config#additionalFiles for more information.`
216+
`The "additionalFiles" option is deprecated and will be removed. Use the "additionalFiles" build extension instead. See https://trigger.dev/docs/guides/new-build-system-preview#additionalfiles for more information.`
217217
);
218218

219219
config.build ??= {};
@@ -224,7 +224,7 @@ function validateConfig(config: TriggerConfig, warn = true) {
224224
if (config.additionalPackages && config.additionalPackages.length > 0) {
225225
warn &&
226226
prettyWarning(
227-
`The "additionalPackages" option is deprecated and will be removed. Use the "additionalPackages" build extension instead. See https://trigger.dev/docs/trigger-config#additionalPackages for more information.`
227+
`The "additionalPackages" option is deprecated and will be removed. Use the "additionalPackages" build extension instead. See https://trigger.dev/docs/guides/new-build-system-preview#additionalpackages for more information.`
228228
);
229229

230230
config.build ??= {};
@@ -260,7 +260,7 @@ function validateConfig(config: TriggerConfig, warn = true) {
260260
if ("resolveEnvVars" in config && typeof config.resolveEnvVars === "function") {
261261
warn &&
262262
prettyWarning(
263-
`The "resolveEnvVars" option is deprecated and will be removed. Use the "syncEnvVars" build extension instead. See https://trigger.dev/docs/trigger-config#syncEnvVars for more information.`
263+
`The "resolveEnvVars" option is deprecated and will be removed. Use the "syncEnvVars" build extension instead. See https://trigger.dev/docs/guides/new-build-system-preview#resolveenvvars for more information.`
264264
);
265265

266266
const resolveEnvVarsFn = config.resolveEnvVars as ResolveEnvironmentVariablesFunction;

0 commit comments

Comments
 (0)