[Components] Add flag for direct imports from components (#42600)

Adds a flag in `convex.json` called `codegen.useApiImports` that enables importing the component types directly from the component instead of blowing out the types.

This works by adding grabbing the import specifier we use to import the `convex.config` and using it to import from `/_generated/component.js` instead. This is the same for both sibling and non-sibling components.

I also added a sample project to exercise this functionality and confirm that it works as expected. We can add an NPM package once they get updated with the new entry point.

GitOrigin-RevId: a9a45f4c616ee1a1032acf984855007324036cbd

Author: jordanhunt22

src/cli/codegen_templates/component_api.ts

@@ -3,7 +3,9 @@ import { Context } from "../../bundler/context.js";
 import { entryPoints } from "../../bundler/index.js";
 import {
   ComponentDirectory,
+  toAbsolutePath,
   toComponentDefinitionPath,
+  ComponentDefinitionPath,
 } from "../lib/components/definition/directoryStructure.js";
 import { StartPushResponse } from "../lib/deployApi/startPush.js";
 import { importPath, moduleIdentifier } from "./api.js";
@@ -64,7 +66,8 @@ export async function componentApiDTS(
   startPush: StartPushResponse,
   rootComponent: ComponentDirectory,
   componentDirectory: ComponentDirectory,
-  opts: { staticApi: boolean },
+  componentsMap: Map<string, ComponentDirectory>,
+  opts: { staticApi: boolean; useComponentApiImports: boolean },
 ) {
   const definitionPath = toComponentDefinitionPath(
     rootComponent,
@@ -103,12 +106,43 @@ export async function componentApiDTS(
         printedMessage: `No analysis found for child component ${childComponent.path}`,
       });
     }
-    for await (const line of codegenExports(
-      ctx,
-      childComponent.name,
-      childComponentAnalysis,
-    )) {
-      lines.push(line);
+    if (opts.useComponentApiImports) {
+      const absolutePath = toAbsolutePath(
+        rootComponent,
+        childComponent.path as ComponentDefinitionPath,
+      );
+
+      let childComponentWithRelativePath = componentsMap?.get(absolutePath);
+      if (!childComponentWithRelativePath) {
+        return await ctx.crash({
+          exitCode: 1,
+          errorType: "fatal",
+          printedMessage: `Invalid child component directory: ${childComponent.path}`,
+        });
+      }
+
+      let importPath;
+
+      // If the user uses a different import specifier than the absolute path of the child component, use the import specifier.
+      if (
+        childComponentWithRelativePath.importSpecifier &&
+        childComponentWithRelativePath.importSpecifier !== childComponent.path
+      ) {
+        importPath = childComponentWithRelativePath.importSpecifier;
+      } else {
+        importPath = `../${childComponent.path}`;
+      }
+      lines.push(
+        `  "${childComponent.name}": import("${importPath}/_generated/component.js").ComponentApi<"${childComponent.name}">,`,
+      );
+    } else {
+      for await (const line of codegenExports(
+        ctx,
+        childComponent.name,
+        childComponentAnalysis,
+      )) {
+        lines.push(line);
+      }
     }
   }
 

src/cli/lib/codegen.ts

@@ -167,17 +167,7 @@ export async function doInitialComponentCodegen(
 ) {
   const { projectConfig } = await readProjectConfig(ctx);
 
-  // This component defined in a dist directory; it is probably in a node_module
-  // directory, installed from a package. It is stuck with the files it has.
-  // Heuristics for this:
-  // - component definition has a dist/ directory as an ancestor
-  // - component definition is a .js file
-  // - presence of .js.map files
-  // We may improve this heuristic.
-  const isPublishedPackage =
-    componentDirectory.definitionPath.endsWith(".js") &&
-    !componentDirectory.isRoot;
-  if (isPublishedPackage) {
+  if (isPublishedPackage(componentDirectory)) {
     if (opts?.verbose) {
       logMessage(
         `skipping initial codegen for installed package ${componentDirectory.path}`,
@@ -239,12 +229,28 @@ export async function doInitialComponentCodegen(
   }
 }
 
+/* This component defined in a dist directory; it is probably in a node_module
+ * directory, installed from a package. It is stuck with the files it has.
+ * Heuristics for this:
+ * - component definition has a dist/ directory as an ancestor
+ * - component definition is a .js file
+ * - presence of .js.map files
+ * We may improve this heuristic.
+ */
+export function isPublishedPackage(componentDirectory: ComponentDirectory) {
+  return (
+    componentDirectory.definitionPath.endsWith(".js") &&
+    !componentDirectory.isRoot
+  );
+}
+
 export async function doFinalComponentCodegen(
   ctx: Context,
   tmpDir: TempDir,
   rootComponent: ComponentDirectory,
   componentDirectory: ComponentDirectory,
   startPushResponse: StartPushResponse,
+  componentsMap: Map<string, ComponentDirectory>,
   opts?: {
     dryRun?: boolean;
     debug?: boolean;
@@ -308,7 +314,11 @@ export async function doFinalComponentCodegen(
     startPushResponse,
     rootComponent,
     componentDirectory,
-    { staticApi: projectConfig.codegen.staticApi },
+    componentsMap,
+    {
+      staticApi: projectConfig.codegen.staticApi,
+      useComponentApiImports: projectConfig.codegen.useComponentApiImports,
+    },
   );
   await writeFormattedFile(
     ctx,

src/cli/lib/components.ts

@@ -352,6 +352,7 @@ async function startComponentsPushAndCodegen(
           rootComponent,
           rootComponent,
           startPushResponse,
+          components,
           options,
         );
         for (const directory of components.values()) {
@@ -361,6 +362,7 @@ async function startComponentsPushAndCodegen(
             rootComponent,
             directory,
             startPushResponse,
+            components,
             options,
           );
         }

src/cli/lib/components/definition/bundle.ts

@@ -356,15 +356,28 @@ async function findComponentDependencies(
     const componentImports = imports.filter((imp) =>
       imp.path.includes(".config."),
     );
-    for (const importPath of componentImports.map((dep) => dep.path)) {
-      const imported = componentsByAbsPath.get(path.resolve(importPath));
+    for (const imp of componentImports) {
+      const imported = componentsByAbsPath.get(path.resolve(imp.path));
       if (!imported) {
         return await ctx.crash({
           exitCode: 1,
           errorType: "invalid filesystem data",
-          printedMessage: `Didn't find ${path.resolve(importPath)} in ${[...componentsByAbsPath.keys()].toString()}`,
+          printedMessage: `Didn't find ${path.resolve(imp.path)} in ${[...componentsByAbsPath.keys()].toString()}`,
         });
       }
+
+      // Grab the import specifier from the metafile (e.g. `@convex-dev/workpool/convex.config`) so
+      // we can use it to import component APIs
+      if (imp.original) {
+        const importSpecifier = imp.original;
+        const relativeSpecifier = importSpecifier.replace(
+          /\/convex\.config.*$/,
+          "",
+        );
+
+        imported.importSpecifier = relativeSpecifier;
+      }
+
       dependencyGraph.push([importer, imported]);
     }
   }

src/cli/lib/components/definition/directoryStructure.ts

@@ -37,6 +37,14 @@ export type ComponentDirectory = {
    * Is this component a root without a config file?
    */
   isRootWithoutConfig: boolean;
+
+  /**
+   * The import specifier used to import this component, with `/convex.config.*` stripped.
+   * For example, if imported as `@convex-dev/workpool/convex.config`, this would be `@convex-dev/workpool`.
+   * For relative imports like `../examples/foo/convex.config.js`, this would be `../examples/foo`.
+   * This is undefined for components discovered through the filesystem (not through imports).
+   */
+  importSpecifier?: string;
 };
 
 /**

src/cli/lib/config.ts

@@ -76,6 +76,7 @@ export interface ProjectConfig {
   codegen: {
     staticApi: boolean;
     staticDataModel: boolean;
+    useComponentApiImports: boolean;
   };
 }
 
@@ -207,9 +208,13 @@ export async function parseProjectConfig(
   if (typeof obj.codegen.staticDataModel === "undefined") {
     obj.codegen.staticDataModel = false;
   }
+  if (typeof obj.codegen.useComponentApiImports === "undefined") {
+    obj.codegen.useComponentApiImports = false;
+  }
   if (
     typeof obj.codegen.staticApi !== "boolean" ||
-    typeof obj.codegen.staticDataModel !== "boolean"
+    typeof obj.codegen.staticDataModel !== "boolean" ||
+    typeof obj.codegen.useComponentApiImports !== "boolean"
   ) {
     return await ctx.crash({
       exitCode: 1,
@@ -319,6 +324,7 @@ export async function readProjectConfig(ctx: Context): Promise<{
         codegen: {
           staticApi: false,
           staticDataModel: false,
+          useComponentApiImports: false,
         },
       },
       configPath: configName(),
@@ -634,6 +640,9 @@ function stripDefaults(projectConfig: ProjectConfig): any {
   if (stripped.codegen.staticDataModel === false) {
     delete stripped.codegen.staticDataModel;
   }
+  if (stripped.codegen.useComponentApiImports === false) {
+    delete stripped.codegen.useComponentApiImports;
+  }
   if (Object.keys(stripped.codegen).length === 0) {
     delete stripped.codegen;
   }
@@ -697,6 +706,7 @@ export async function pullConfig(
       codegen: {
         staticApi: false,
         staticDataModel: false,
+        useComponentApiImports: false,
       },
       project,
       team,