Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(fumadocs): document Twoslash patterns and SDK types

Sushmithamallesh251f8b0bdfbd
diff --git a/fumadocs/CLAUDE.md b/fumadocs/CLAUDE.md
index bd54434a8..8765c9423 100644
--- a/fumadocs/CLAUDE.md
+++ b/fumadocs/CLAUDE.md
@@ -51,11 +51,14 @@ CI auto-generates on changes to `ts/packages/core/src/**` or `python/composio/**
- **Build-time validation**: Type errors fail the build.
- **CI enforcement**: `.github/workflows/docs-typescript-check.yml` runs on PRs to fumadocs/
+### Exclusions
+- **Reference docs** (`/content/reference/`): Excluded from Twoslash via collection-level `mdxOptions` in `source.config.ts`. These are auto-generated and don't need type checking.
+
### Common patterns
**Basic snippet with setup code (hidden from output):**
````md
-```typescript twoslash
+```typescript
import { Composio } from '@composio/core';
const composio = new Composio({ apiKey: 'key' });
const userId = 'user_123';
@@ -65,7 +68,25 @@ const tools = await composio.tools.get(userId, { toolkits: ['GITHUB'] });
```
````
-**Skip type checking (for external deps or pseudocode):**
+**Using SDK-exported types for callbacks:**
+The SDK exports types for modifiers - use them instead of inline type annotations:
+````md
+```typescript
+import { Composio, TransformToolSchemaModifier } from '@composio/core';
+
+const modifySchema: TransformToolSchemaModifier = ({ toolSlug, toolkitSlug, schema }) => {
+ // TypeScript infers all parameter types!
+ return schema;
+};
+```
+````
+
+Available modifier types from `@composio/core`:
+- `beforeExecuteModifier` - for `beforeExecute` callbacks
+- `afterExecuteModifier` - for `afterExecute` callbacks
+- `TransformToolSchemaModifier` - for `modifySchema` callbacks
+
+**Skip type checking (for partial snippets or external deps):**
````md
```typescript
// @noErrors
@@ -73,6 +94,19 @@ import { SomeExternalThing } from 'not-installed-package';
```
````
+**Declare external variables in hidden section:**
+When code uses variables that aren't defined in the snippet, declare them before the cut:
+````md
+```typescript
+import { Composio } from '@composio/core';
+
+declare const composio: Composio;
+declare const userId: string;
+// ---cut---
+const tools = await composio.tools.get(userId, { toolkits: ['GITHUB'] });
+```
+````
+
### Annotations
- `// ---cut---` - Hide code above from output (but include for compilation)
- `// @noErrors` - Skip all type checking for this block
@@ -82,12 +116,15 @@ import { SomeExternalThing } from 'not-installed-package';
### Configuration
- **Config**: `source.config.ts` - `transformerTwoslash({ explicitTrigger: false })`
- **SDK packages**: Installed as devDependencies for import resolution
+- **Reference exclusion**: Uses `applyMdxPreset` with custom `rehypeCodeOptions` (no twoslash transformer)
### Troubleshooting
- If imports fail, ensure the package is in `devDependencies`
- Use `// @noErrors` for examples with external dependencies not in package.json
- Use `// ---cut---` to add setup code (imports, variable declarations) that compiles but isn't shown
- Check CI logs for specific error codes (e.g., 2304 = cannot find name, 2322 = type mismatch)
+- For callback types, prefer importing SDK types over inline `{ foo: string; bar: any }` annotations
+- Run `bun run build` locally to validate all code blocks before pushing
## Deployment
- Vercel project: `composio/fumadocs`
diff --git a/fumadocs/README.md b/fumadocs/README.md
index 72d65b4ca..edabc6efa 100644
--- a/fumadocs/README.md
+++ b/fumadocs/README.md
@@ -64,11 +64,21 @@ Each folder has `meta.json` for ordering:
}
```
+## TypeScript Code Blocks
+
+All TypeScript code blocks in MDX files are **type-checked at build time** using Twoslash. This ensures docs stay in sync with the SDK.
+
+- Use `// @noErrors` to skip checking for partial snippets
+- Use `// ---cut---` to hide setup code from output
+- Run `bun run build` locally to validate before pushing
+
+See `CLAUDE.md` for detailed patterns and troubleshooting.
+
## Commands
| Command | Description |
|---------|-------------|
| `bun run dev` | Dev server |
-| `bun run build` | Production build |
+| `bun run build` | Production build (validates TS code blocks) |
| `bun run types:check` | Type check |