Add typescriptCompiler option to convex.json (#44027)

GitOrigin-RevId: af88d968d773b1f860d9784cc658264af8b9716d

Author: reeceyang

npm-packages/common/config/rush/pnpm-lock.yaml

@@ -76,6 +76,11 @@
           "default": false
         }
       }
+    },
+    "typescriptCompiler": {
+      "type": "string",
+      "enum": ["tsc", "tsgo"],
+      "description": "TypeScript compiler to use for typechecking (`@typescript/native-preview` must be installed to use `tsgo`)"
     }
   },
   "additionalProperties": false

npm-packages/convex/schemas/convex.schema.json

@@ -4,6 +4,7 @@ import { EOL } from "os";
 import path from "path";
 import { z } from "zod";
 import { Context } from "../../bundler/context.js";
+import { TypescriptCompiler } from "./typecheck.js";
 import {
   changeSpinner,
   logError,
@@ -92,6 +93,8 @@ export interface ProjectConfig {
     legacyComponentApi?: boolean;
     fileType?: "ts" | "js/dts";
   };
+
+  typescriptCompiler?: TypescriptCompiler;
 }
 
 /** Type written to convex.json (where we elide deleted default values)  */
@@ -204,6 +207,12 @@ const createProjectConfigSchema = (strict: boolean) => {
       staticDataModel: false,
     }),
     generateCommonJSApi: z.boolean().default(false),
+    typescriptCompiler: z
+      .enum(["tsc", "tsgo"])
+      .optional()
+      .describe(
+        "TypeScript compiler to use for typechecking (`@typescript/native-preview` must be installed to use `tsgo`)",
+      ),
 
     // Optional $schema field for JSON schema validation in editors
     $schema: z.string().optional(),

npm-packages/convex/src/cli/lib/config.ts

@@ -5,11 +5,26 @@ import { logError, logFailure, showSpinner } from "../../bundler/log.js";
 import * as Sentry from "@sentry/node";
 import * as semver from "semver";
 import { spawnAsync } from "./utils/utils.js";
+import { readProjectConfig } from "./config.js";
 
 export type TypecheckResult = "cantTypeCheck" | "success" | "typecheckFailed";
 
 export type TypeCheckMode = "enable" | "try" | "disable";
 
+export type TypescriptCompiler = "tsc" | "tsgo";
+
+/**
+ * Resolves the TypeScript compiler to use based on CLI flag, config file, and default.
+ * Precedence: CLI flag → config file → default "tsc"
+ */
+export async function resolveTypescriptCompiler(
+  ctx: Context,
+  cliOption?: TypescriptCompiler,
+): Promise<TypescriptCompiler> {
+  const { projectConfig } = await readProjectConfig(ctx);
+  return cliOption ?? projectConfig?.typescriptCompiler ?? "tsc";
+}
+
 type TypecheckResultHandler = (
   result: TypecheckResult,
   logSpecificError?: () => void,
@@ -36,8 +51,10 @@ export async function typeCheckFunctionsInMode(
   if (typeCheckMode === "disable") {
     return;
   }
+  const typescriptCompiler = await resolveTypescriptCompiler(ctx);
   await typeCheckFunctions(
     ctx,
+    typescriptCompiler,
     functionsDir,
     async (result, logSpecificError, runOnError) => {
       if (
@@ -72,6 +89,7 @@ export async function typeCheckFunctionsInMode(
 // Runs TypeScript compiler to typecheck Convex query and mutation functions.
 export async function typeCheckFunctions(
   ctx: Context,
+  typescriptCompiler: TypescriptCompiler,
   functionsDir: string,
   handleResult: TypecheckResultHandler,
 ): Promise<void> {
@@ -84,20 +102,37 @@ export async function typeCheckFunctions(
       logError("Run `npx convex codegen --init` to create one.");
     });
   }
-  await runTsc(ctx, ["--project", functionsDir], handleResult);
+  await runTsc(
+    ctx,
+    typescriptCompiler,
+    ["--project", functionsDir],
+    handleResult,
+  );
 }
 
 async function runTsc(
   ctx: Context,
+  typescriptCompiler: TypescriptCompiler,
   tscArgs: string[],
   handleResult: TypecheckResultHandler,
 ): Promise<void> {
   // Check if tsc is even installed
-  const tscPath = path.join("node_modules", "typescript", "bin", "tsc");
+  const tscPath =
+    typescriptCompiler === "tsgo"
+      ? path.join(
+          "node_modules",
+          "@typescript",
+          "native-preview",
+          "bin",
+          "tsgo.js",
+        )
+      : path.join("node_modules", "typescript", "bin", "tsc");
   if (!ctx.fs.exists(tscPath)) {
     return handleResult("cantTypeCheck", () => {
       logError(
-        chalkStderr.gray("No TypeScript binary found, so skipping typecheck."),
+        chalkStderr.gray(
+          `No \`${typescriptCompiler}\` binary found, so skipping typecheck.`,
+        ),
       );
     });
   }

npm-packages/convex/src/cli/lib/typecheck.ts

@@ -1,8 +1,11 @@
 import { chalkStderr } from "chalk";
 import { functionsDir, ensureHasConvexDependency } from "./lib/utils/utils.js";
-import { Command } from "@commander-js/extra-typings";
+import { Command, Option } from "@commander-js/extra-typings";
 import { readConfig } from "./lib/config.js";
-import { typeCheckFunctions } from "./lib/typecheck.js";
+import {
+  typeCheckFunctions,
+  resolveTypescriptCompiler,
+} from "./lib/typecheck.js";
 import { oneoffContext } from "../bundler/context.js";
 import { logFinishedStep, logMessage } from "../bundler/log.js";
 
@@ -17,16 +20,27 @@ export const typecheck = new Command("typecheck")
     "Run TypeScript typechecking on your Convex functions with `tsc --noEmit`.",
   )
   .allowExcessArguments(false)
-  .action(async () => {
+  .addOption(
+    new Option(
+      "--typescript-compiler <compiler>",
+      "TypeScript compiler to use for typechecking (`@typescript/native-preview` must be installed to use `tsgo`)",
+    ).choices(["tsc", "tsgo"] as const),
+  )
+  .action(async (cmdOptions) => {
     const ctx = await oneoffContext({
       url: undefined,
       adminKey: undefined,
       envFile: undefined,
     });
+    const typescriptCompiler = await resolveTypescriptCompiler(
+      ctx,
+      cmdOptions.typescriptCompiler,
+    );
     const { configPath, config: localConfig } = await readConfig(ctx, false);
     await ensureHasConvexDependency(ctx, "typecheck");
     await typeCheckFunctions(
       ctx,
+      typescriptCompiler,
       functionsDir(configPath, localConfig.projectConfig),
       async (typecheckResult, logSpecificError, runOnError) => {
         logSpecificError?.();
@@ -55,7 +69,7 @@ export const typecheck = new Command("typecheck")
           });
         } else {
           logFinishedStep(
-            "Typecheck passed: `tsc --noEmit` completed with exit code 0.",
+            `Typecheck passed: \`${typescriptCompiler} --noEmit\` completed with exit code 0.`,
           );
           return await ctx.flushAndExit(0);
         }

npm-packages/convex/src/cli/typecheck.ts

@@ -0,0 +1,2 @@
+
+.env.local

npm-packages/private-demos/tsgo-test/.gitignore

@@ -0,0 +1,4 @@
+{
+  "typescriptCompiler": "tsgo",
+  "$schema": "https://raw.githubusercontent.com/get-convex/convex-backend/refs/heads/main/npm-packages/convex/schemas/convex.schema.json"
+}

npm-packages/private-demos/tsgo-test/convex.json

@@ -0,0 +1,49 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as example from "../example.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  example: typeof example;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

npm-packages/private-demos/tsgo-test/convex/_generated/api.d.ts

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();