TypeScript: Introduce createGenerator API

Author: fuma-nama

.changeset/social-moons-roll.md

@@ -0,0 +1,48 @@
+---
+'fumadocs-typescript': major
+---
+
+**Use `createGenerator` API**
+
+Create a generator instance:
+
+```ts
+import { createGenerator } from 'fumadocs-typescript';
+
+const generator = createGenerator(tsconfig);
+```
+
+Refactor:
+
+```tsx
+import { remarkAutoTypeTable, createTypeTable } from 'fumadocs-typescript';
+
+generateDocumentation('./file.ts', 'MyClass', fs.readFileSync('./file.ts').toString())
+generateMDX('content', {...})
+generateFiles({...})
+const processor = createProcessor({
+    remarkPlugins: [remarkAutoTypeTable],
+});
+
+const AutoTypeTable = createTypeTable()
+return <AutoTypeTable {...props} />
+```
+
+To:
+
+```tsx
+import { AutoTypeTable, remarkAutoTypeTable } from "fumadocs-typescript";
+
+generator.generateDocumentation({path: './file.ts'}, 'MyClass')
+generateMDX(generator, 'content', { ... })
+generateFiles(generator, { ... })
+const processor = createProcessor({
+    remarkPlugins: [
+        [remarkAutoTypeTable, { generator }],
+    ],
+});
+
+return <AutoTypeTable generator={generator} {...props} />
+```
+
+This ensure the compiler instance is always re-used.

apps/docs/app/docs/[...slug]/page.tsx

@@ -22,7 +22,6 @@ import * as Preview from '@/components/preview';
 import { createMetadata } from '@/lib/metadata';
 import { openapi, source } from '@/lib/source';
 import { Wrapper } from '@/components/preview/wrapper';
-import { AutoTypeTable } from '@/components/type-table';
 import { metadataImage } from '@/lib/metadata-image';
 import { File, Folder, Files } from 'fumadocs-ui/components/files';
 import { Mermaid } from '@theguild/remark-mermaid/mermaid';
@@ -37,6 +36,8 @@ import {
 } from '@/components/ui/hover-card';
 import Link from 'fumadocs-core/link';
 import { UiOverview } from '@/components/ui-overview';
+import { AutoTypeTable } from 'fumadocs-typescript/ui';
+import { createGenerator } from 'fumadocs-typescript';
 
 function PreviewRenderer({ preview }: { preview: string }): ReactNode {
   if (preview && preview in Preview) {
@@ -47,6 +48,8 @@ function PreviewRenderer({ preview }: { preview: string }): ReactNode {
   return null;
 }
 
+const generator = createGenerator();
+
 export const revalidate = false;
 
 export default async function Page(props: {
@@ -123,7 +126,9 @@ export default async function Page(props: {
             Tab,
             Mermaid,
             TypeTable,
-            AutoTypeTable,
+            AutoTypeTable: (props) => (
+              <AutoTypeTable generator={generator} {...props} />
+            ),
             Accordion,
             Accordions,
             Wrapper,

apps/docs/components/type-table.ts

@@ -18,22 +18,26 @@ It comes with the `AutoTypeTable` component. Learn more about [Auto Type Table](
 You can use it as a remark plugin:
 
 ```ts title="source.config.ts" tab="Fumadocs MDX"
-import { remarkAutoTypeTable } from 'fumadocs-typescript';
+import { remarkAutoTypeTable, createGenerator } from 'fumadocs-typescript';
 import { defineConfig } from 'fumadocs-mdx/config';
 
+const generator = createGenerator();
+
 export default defineConfig({
   mdxOptions: {
-    remarkPlugins: [remarkAutoTypeTable],
+    remarkPlugins: [[remarkAutoTypeTable, { generator }]],
   },
 });
 ```
 
 ```ts tab="MDX Compiler"
-import { remarkAutoTypeTable } from 'fumadocs-typescript';
+import { remarkAutoTypeTable, createGenerator } from 'fumadocs-typescript';
 import { compile } from '@mdx-js/mdx';
 
+const generator = createGenerator();
+
 await compile('...', {
-  remarkPlugins: [remarkAutoTypeTable],
+  remarkPlugins: [[remarkAutoTypeTable, { generator }]],
 });
 ```
 

apps/docs/content/docs/ui/(integrations)/typescript.mdx

@@ -41,17 +41,22 @@ fumadocs-typescript
 Initialize the TypeScript compiler and add it as a MDX component.
 
 ```tsx title="page.tsx"
-import { createTypeTable } from 'fumadocs-typescript/ui';
+import { createGenerator } from 'fumadocs-typescript';
+import { AutoTypeTable } from 'fumadocs-typescript/ui';
 import defaultMdxComponents from 'fumadocs-ui/mdx';
 
-const { AutoTypeTable } = createTypeTable();
-
-<MDX
-  components={{
-    ...defaultMdxComponents,
-    AutoTypeTable,
-  }}
-/>;
+const generator = createGenerator();
+
+return (
+  <MDX
+    components={{
+      ...defaultMdxComponents,
+      AutoTypeTable: (props) => (
+        <AutoTypeTable {...props} generator={generator} />
+      ),
+    }}
+  />
+);
 ```
 
 ### From File

apps/docs/content/docs/ui/components/auto-type-table.mdx

@@ -1,11 +1,12 @@
 import {
   type ExportedDeclarations,
-  type Project,
+  Project,
   type Symbol as TsSymbol,
   ts,
   type Type,
 } from 'ts-morph';
 import { getProject, type TypescriptConfig } from '@/get-project';
+import fs from 'node:fs';
 
 export interface GeneratedDoc {
   name: string;
@@ -49,44 +50,68 @@ export interface GenerateOptions {
   transform?: Transformer;
 }
 
-export interface GenerateDocumentationOptions extends GenerateOptions {
-  /**
-   * Typescript configurations
-   */
-  config?: TypescriptConfig;
-  project?: Project;
+export type Generator = ReturnType<typeof createGenerator>;
+
+export function createGenerator(config?: TypescriptConfig | Project) {
+  const project = config instanceof Project ? config : getProject(config);
+
+  return {
+    generateDocumentation(
+      file: {
+        path: string;
+        content?: string;
+      },
+      name: string | undefined,
+      options: GenerateOptions = {},
+    ) {
+      const sourceFile = project.createSourceFile(
+        file.path,
+        file.content ?? fs.readFileSync(file.path).toString(),
+        {
+          overwrite: true,
+        },
+      );
+      const out: GeneratedDoc[] = [];
+
+      for (const [k, d] of sourceFile.getExportedDeclarations()) {
+        if (name && name !== k) continue;
+
+        if (d.length > 1)
+          console.warn(
+            `export ${k} should not have more than one type declaration.`,
+          );
+
+        out.push(generate(project, k, d[0], options));
+      }
+
+      return out;
+    },
+  };
 }
 
 /**
  * Generate documentation for properties in an exported type/interface
+ *
+ * @deprecated use `createGenerator` instead
  */
 export function generateDocumentation(
   file: string,
   name: string | undefined,
   content: string,
-  options: GenerateDocumentationOptions = {},
+  options: GenerateOptions & {
+    /**
+     * Typescript configurations
+     */
+    config?: TypescriptConfig;
+    project?: Project;
+  } = {},
 ): GeneratedDoc[] {
-  const project = options.project ?? getProject(options.config);
-  const sourceFile = project.createSourceFile(file, content, {
-    overwrite: true,
-  });
-  const out: GeneratedDoc[] = [];
-
-  for (const [k, d] of sourceFile.getExportedDeclarations()) {
-    if (name && name !== k) continue;
-
-    if (d.length > 1)
-      console.warn(
-        `export ${k} should not have more than one type declaration.`,
-      );
-
-    out.push(generate(project, k, d[0], options));
-  }
+  const gen = createGenerator(options.project ?? options.config);
 
-  return out;
+  return gen.generateDocumentation({ path: file, content }, name, options);
 }
 
-export function generate(
+function generate(
   program: Project,
   name: string,
   declaration: ExportedDeclarations,

packages/typescript/src/lib/base.ts

@@ -1,8 +1,8 @@
 import * as path from 'node:path';
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import fg from 'fast-glob';
-import { getProject } from '@/get-project';
 import { generateMDX, type GenerateMDXOptions } from './mdx';
+import type { Generator } from '@/lib/base';
 
 export interface GenerateFilesOptions {
   input: string | string[];
@@ -20,11 +20,10 @@ export interface GenerateFilesOptions {
 }
 
 export async function generateFiles(
+  generator: Generator,
   options: GenerateFilesOptions,
 ): Promise<void> {
   const files = await fg(options.input, options.globOptions);
-  const project =
-    options.options?.project ?? getProject(options.options?.config);
 
   const produce = files.map(async (file) => {
     const absolutePath = path.resolve(file);
@@ -37,10 +36,9 @@ export async function generateFiles(
           );
 
     const content = (await readFile(absolutePath)).toString();
-    let result = generateMDX(content, {
+    let result = generateMDX(generator, content, {
       basePath: path.dirname(absolutePath),
       ...options.options,
-      project,
     });
 
     if (options.transformOutput) {

packages/typescript/src/lib/file.ts

@@ -1,19 +1,17 @@
 import * as path from 'node:path';
-import fs from 'node:fs';
-import { getProject } from '@/get-project';
 import {
   type DocEntry,
   type GeneratedDoc,
-  generateDocumentation,
-  type GenerateDocumentationOptions,
+  type Generator,
+  type GenerateOptions,
 } from './base';
 
 interface Templates {
   block: (doc: GeneratedDoc, children: string) => string;
   property: (entry: DocEntry) => string;
 }
 
-export interface GenerateMDXOptions extends GenerateDocumentationOptions {
+export interface GenerateMDXOptions extends GenerateOptions {
   /**
    * a root directory to resolve relative file paths
    */
@@ -49,23 +47,23 @@ ${Object.entries(c.tags)
 };
 
 export function generateMDX(
+  generator: Generator,
   source: string,
   { basePath = './', templates: overrides, ...rest }: GenerateMDXOptions = {},
 ): string {
   const templates = { ...defaultTemplates, ...overrides };
-  const project = rest.project ?? getProject(rest.config);
 
   return source.replace(regex, (...args) => {
     const groups = args[args.length - 1] as {
       file: string;
       name: string | undefined;
     };
     const file = path.resolve(basePath, groups.file);
-    const content = fs.readFileSync(file);
-    const docs = generateDocumentation(file, groups.name, content.toString(), {
-      ...rest,
-      project,
-    });
+    const docs = generator.generateDocumentation(
+      { path: file },
+      groups.name,
+      rest,
+    );
 
     return docs
       .map((doc) =>