fix(build): support decorator metadata with TypeScript 7

.changeset/typescript-seven-builds.md

@@ -10,4 +10,4 @@
 "@trigger.dev/sdk": patch
 ---
 
-Refresh package builds for TypeScript 7 compatibility while preserving existing runtime entry points. TypeScript remains an optional peer for the decorator metadata build extension, so installing the Trigger.dev CLI does not install an additional compiler.
+Refresh package builds for TypeScript 7 compatibility while preserving existing runtime entry points. Projects using `emitDecoratorMetadata()` with TypeScript 7 can install the `@typescript/typescript6` compatibility package alongside it; the package remains optional, so installing the Trigger.dev CLI does not install an additional compiler.

docs/config/extensions/emitDecoratorMetadata.mdx

@@ -22,8 +22,31 @@ export default defineConfig({
 This is usually required if you are using certain ORMs, like TypeORM, that require this option to be enabled. It's not enabled by default because there is a performance cost to enabling it.
 
 <Note>
- emitDecoratorMetadata works by hooking into the esbuild bundle process and using the TypeScript
- compiler API to compile files where we detect the use of decorators. This means you must have
- `emitDecoratorMetadata` enabled in your `tsconfig.json` file, as well as `typescript` installed in
- your `devDependencies`.
+ `emitDecoratorMetadata` hooks into the esbuild bundle process and uses the TypeScript compiler API
+ to compile files containing decorators. Enable `emitDecoratorMetadata` in your `tsconfig.json` and
+ install `typescript` in your `devDependencies`.
 </Note>
+
+## Using with TypeScript 7
+
+TypeScript 7 does not expose the JavaScript compiler API required by this extension. Install the TypeScript 6 compatibility package alongside TypeScript 7:
+
+<CodeGroup>
+
+```bash npm
+npm install --save-dev @typescript/typescript6@latest
+```
+
+```bash pnpm
+pnpm add --save-dev @typescript/typescript6@latest
+```
+
+```bash bun
+bun add --dev @typescript/typescript6@latest
+```
+
+</CodeGroup>
+
+Your project continues using TypeScript 7 for its normal type checking and compiler commands. The extension loads the compatibility package only when it needs to emit decorator metadata.
+
+Restart the Trigger.dev dev server after installing the package.

packages/build/package.json

@@ -89,16 +89,23 @@
  "devDependencies": {
  "@arethetypeswrong/cli": "^0.18.5",
  "@types/resolve": "^1.20.6",
+ "@typescript/typescript6": "6.0.2",
  "esbuild": "^0.23.0",
  "rimraf": "6.0.1",
  "tshy": "^4.1.3",
  "tsx": "4.17.0",
- "typescript": "6.0.3"
+ "typescript": "6.0.3",
+ "typescript5": "npm:typescript@5.9.3",
+ "typescript7": "npm:typescript@7.0.2"
  },
  "peerDependencies": {
+ "@typescript/typescript6": "^6.0.0",
  "typescript": ">=5.0.0"
  },
  "peerDependenciesMeta": {
+ "@typescript/typescript6": {
+ "optional": true
+ },
  "typescript": {
  "optional": true
  }

packages/build/src/extensions/internal/loadTypescript.test.ts

@@ -0,0 +1,133 @@
+import { createRequire } from "node:module";
+import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadTypescript } from "./loadTypescript.js";
+
+const packageRequire = createRequire(join(process.cwd(), "package.json"));
+const projectDirs = new Set<string>();
+
+function createProject(packages: Record<string, string>) {
+ const projectDir = mkdtempSync(join(tmpdir(), "trigger-typescript-"));
+ projectDirs.add(projectDir);
+ const nodeModulesDir = join(projectDir, "node_modules");
+
+ mkdirSync(nodeModulesDir);
+ writeFileSync(join(projectDir, "package.json"), JSON.stringify({ private: true }));
+
+ for (const [installedName, sourceName] of Object.entries(packages)) {
+ const target = dirname(packageRequire.resolve(`${sourceName}/package.json`));
+ const destination = join(nodeModulesDir, installedName);
+
+ mkdirSync(dirname(destination), { recursive: true });
+ symlinkSync(target, destination, "junction");
+ }
+
+ return projectDir;
+}
+
+function createBrokenCompiler(projectDir: string, packageName = "typescript") {
+ const packageDir = join(projectDir, "node_modules", packageName);
+
+ mkdirSync(packageDir, { recursive: true });
+ writeFileSync(
+ join(packageDir, "package.json"),
+ JSON.stringify({ name: packageName, main: "index.cjs" })
+ );
+ writeFileSync(join(packageDir, "index.cjs"), 'throw new Error("broken compiler");');
+}
+
+describe("loadTypescript", () => {
+ afterEach(() => {
+ for (const projectDir of projectDirs) {
+ rmSync(projectDir, { recursive: true, force: true });
+ }
+
+ projectDirs.clear();
+ });
+
+ it("loads the consumer's TypeScript 5 compiler", () => {
+ const compiler = loadTypescript(createProject({ typescript: "typescript5" }));
+
+ expect(compiler.version).toBe("5.9.3");
+ expect(typeof compiler.transpileModule).toBe("function");
+ });
+
+ it("loads the consumer's TypeScript 6 compiler", () => {
+ const compiler = loadTypescript(createProject({ typescript: "typescript" }));
+
+ expect(compiler.version).toBe("6.0.3");
+ expect(typeof compiler.transpileModule).toBe("function");
+ });
+
+ it("returns an actionable error for TypeScript 7 without the compatibility package", () => {
+ const projectDir = createProject({ typescript: "typescript7" });
+ const requireFromProject = createRequire(join(projectDir, "package.json"));
+
+ expect(typeof requireFromProject("typescript").transpileModule).toBe("undefined");
+ expect(() => loadTypescript(projectDir, ["typescript"])).toThrowError(
+ expect.objectContaining({
+ message: expect.stringContaining("npm install --save-dev @typescript/typescript6"),
+ })
+ );
+ });
+
+ it("surfaces errors from an installed compiler package", () => {
+ const projectDir = createProject({});
+ createBrokenCompiler(projectDir);
+
+ expect(() => loadTypescript(projectDir, ["typescript"])).toThrowError(
+ `Failed to load "typescript" from ${projectDir}.`
+ );
+ });
+
+ it("falls back when an earlier compiler package fails to load", () => {
+ const projectDir = createProject({
+ "@typescript/typescript6": "@typescript/typescript6",
+ });
+ createBrokenCompiler(projectDir);
+
+ const compiler = loadTypescript(projectDir);
+
+ expect(compiler.version).toBe("6.0.3");
+ expect(typeof compiler.transpileModule).toBe("function");
+ });
+
+ it("falls back to the TypeScript 6 compatibility package for TypeScript 7", () => {
+ const compiler = loadTypescript(
+ createProject({
+ typescript: "typescript7",
+ "@typescript/typescript6": "@typescript/typescript6",
+ })
+ );
+
+ const output = compiler.transpileModule(
+ `
+ class Dependency {}
+ function injectable<T extends new (...args: any[]) => object>(target: T) {}
+
+ @injectable
+ class Service {
+ constructor(public dependency: Dependency) {}
+ }
+ `,
+ {
+ compilerOptions: {
+ experimentalDecorators: true,
+ emitDecoratorMetadata: true,
+ },
+ }
+ ).outputText;
+
+ expect(compiler.version).toBe("6.0.3");
+ expect(output).toContain('__metadata("design:paramtypes", [Dependency])');
+ });
+
+ it("supports aliasing TypeScript to the compatibility package", () => {
+ const compiler = loadTypescript(createProject({ typescript: "@typescript/typescript6" }));
+
+ expect(compiler.version).toBe("6.0.3");
+ expect(typeof compiler.transpileModule).toBe("function");
+ });
+});

packages/build/src/extensions/internal/loadTypescript.ts

@@ -0,0 +1,85 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+export type TypeScriptCompiler = typeof import("typescript");
+
+const compilerPackages = ["typescript", "@typescript/typescript6"] as const;
+
+function hasTranspileModule(value: unknown): value is TypeScriptCompiler {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ "transpileModule" in value &&
+ typeof value.transpileModule === "function"
+ );
+}
+
+function isUnavailablePackage(error: unknown) {
+ return (
+ error instanceof Error &&
+ "code" in error &&
+ (error.code === "MODULE_NOT_FOUND" || error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+ );
+}
+
+export function loadTypescript(
+ projectDir: string,
+ packageNames: readonly string[] = compilerPackages
+): TypeScriptCompiler {
+ const requireFromProject = createRequire(join(projectDir, "package.json"));
+ const loadErrors: Error[] = [];
+
+ for (const packageName of packageNames) {
+ let resolvedPackage: string;
+
+ try {
+ resolvedPackage = requireFromProject.resolve(packageName);
+ } catch (error) {
+ if (isUnavailablePackage(error)) {
+ continue;
+ }
+
+ throw error;
+ }
+
+ let compiler: unknown;
+
+ try {
+ compiler = requireFromProject(resolvedPackage);
+ } catch (error) {
+ loadErrors.push(
+ new Error(`Failed to load "${packageName}" from ${projectDir}.`, { cause: error })
+ );
+ continue;
+ }
+
+ if (hasTranspileModule(compiler)) {
+ return compiler;
+ }
+ }
+
+ if (loadErrors.length === 1) {
+ throw loadErrors[0];
+ }
+
+ if (loadErrors.length > 1) {
+ throw new AggregateError(
+ loadErrors,
+ `Failed to load a compatible TypeScript compiler from ${projectDir}.`
+ );
+ }
+
+ throw new Error(
+ [
+ "The emitDecoratorMetadata() build extension requires the TypeScript JavaScript compiler API,",
+ "which TypeScript 7 does not expose.",
+ "",
+ "Install the TypeScript 6 compatibility package alongside TypeScript 7:",
+ "",
+ " npm install --save-dev @typescript/typescript6",
+ "",
+ "Restart the Trigger.dev dev server after installing the package.",
+ "See https://trigger.dev/docs/config/extensions/emitDecoratorMetadata#using-with-typescript-7",
+ ].join("\n")
+ );
+}

packages/build/src/extensions/typescript.ts

@@ -1,36 +1,43 @@
 import { BuildExtension } from "@trigger.dev/core/v3/build";
 import { readFile } from "node:fs/promises";
-import typescriptPkg from "typescript";
-
-const { transpileModule, ModuleKind } = typescriptPkg;
+import { dirname } from "node:path";
+import { loadTypescript } from "./internal/loadTypescript.js";
 
 const decoratorMatcher = new RegExp(/((?<![(\s]\s*['"])@\w[.[\]\w\d]*\s*(?![;])[((?=\s)])/);
 
 export function emitDecoratorMetadata(): BuildExtension {
  return {
  name: "emitDecoratorMetadata",
  onBuildStart(context) {
+ const { convertCompilerOptionsFromJson, transpileModule, ModuleKind } = loadTypescript(
+ context.workingDir
+ );
+
  context.registerPlugin({
  name: "emitDecoratorMetadata",
  async setup(build) {
- const { parseNative, TSConfckCache } = await import("tsconfck");
+ const { parse, TSConfckCache } = await import("tsconfck");
  const cache = new TSConfckCache<any>();
 
  build.onLoad({ filter: /\.ts$/ }, async (args) => {
  context.logger.debug("emitDecoratorMetadata onLoad", { args });
 
- const { tsconfigFile, tsconfig } = await parseNative(args.path, {
+ const { tsconfigFile, tsconfig } = await parse(args.path, {
  ignoreNodeModules: true,
  cache,
  });
+ const { options: compilerOptions } = convertCompilerOptionsFromJson(
+ tsconfig.compilerOptions ?? {},
+ tsconfigFile ? dirname(tsconfigFile) : context.workingDir
+ );
 
- context.logger.debug("emitDecoratorMetadata parsed native tsconfig", {
+ context.logger.debug("emitDecoratorMetadata parsed tsconfig", {
  tsconfig,
  tsconfigFile,
  args,
  });
 
- if (tsconfig.compilerOptions?.emitDecoratorMetadata !== true) {
+ if (compilerOptions.emitDecoratorMetadata !== true) {
  context.logger.debug("emitDecoratorMetadata skipping", {
  args,
  tsconfig,
@@ -55,7 +62,7 @@ export function emitDecoratorMetadata(): BuildExtension {
  const program = transpileModule(ts, {
  fileName: args.path,
  compilerOptions: {
- ...tsconfig.compilerOptions,
+ ...compilerOptions,
  module: ModuleKind.ES2022,
  },
  });