Skip to main content

Documentation Index

Fetch the complete documentation index at: https://smithers.sh/llms.txt

Use this file to discover all available pages before exploring further.

Build and package configuration shipped with smithers-orchestrator. Use it when setting up a new project, debugging import resolution, or understanding why your tsconfig.json needs specific options.

​
Binary

Use bunx smithers-orchestrator <command> for CLI commands. The repository root keeps a private development bin that points at apps/cli/src/index.js; application code should import from the package exports below.

​
Subpath Exports

Use the subpath form to import only the surface you need.
Import pathEntry filePurpose
smithers-orchestrator./src/index.jsCore API: createSmithers, components, runWorkflow, renderMdx, errors
smithers-orchestrator/gateway./src/gateway.jsGateway client for remote workflow coordination
smithers-orchestrator/jsx-runtime./src/jsx-runtime.jsJSX runtime (auto-resolved by jsxImportSource)
smithers-orchestrator/jsx-dev-runtime./src/jsx-runtime.jsJSX dev runtime (auto-resolved in dev mode)
smithers-orchestrator/tools./src/tools.jsTool sandbox: defineTool, read, grep, bash, edit, write
smithers-orchestrator/server./src/server.jsHTTP server for run management and event streaming
smithers-orchestrator/observability./src/observability.jsOpenTelemetry traces, metrics, and Prometheus integration
smithers-orchestrator/pi-plugin./src/pi-plugin.jsPI CLI agent plugin
smithers-orchestrator/pi-extension./src/pi-extension.jsPI extension UI bridge
smithers-orchestrator/mdx-plugin./src/mdx-plugin.jsBun preload plugin for .mdx imports
smithers-orchestrator/dom/renderer./src/dom/renderer.jsInternal renderer (advanced use)
smithers-orchestrator/serve./src/serve.jsSingle-workflow HTTP server via createServeApp
smithers-orchestrator/scorers./src/scorers.jsEval scorers: createScorer, llmJudge, aggregate
smithers-orchestrator/memory./src/memory.jsCross-run memory storage and recall
smithers-orchestrator/openapi./src/openapi.jsGenerate AI SDK tools from OpenAPI specs

​
Usage

// Core API
import { createSmithers, runWorkflow } from "smithers-orchestrator";

// Tools
import { defineTool, bash, read, write } from "smithers-orchestrator/tools";

// Scorers
import { createScorer, llmJudge } from "smithers-orchestrator/scorers";

// MDX plugin (in preload.ts)
import { mdxPlugin } from "smithers-orchestrator/mdx-plugin";

​
TypeScript Configuration

​
JSX Import Source

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "smithers-orchestrator"
  }
}
This tells TypeScript to resolve JSX transforms from smithers-orchestrator/jsx-runtime instead of react/jsx-runtime. The Smithers JSX runtime re-exports React’s runtime, so component behavior is identical — this setting enables proper type resolution for Smithers workflow components. See JSX Installation for the complete TypeScript setup.

​
Path Aliases

When developing inside the smithers-orchestrator monorepo, the root tsconfig.json defines path aliases so source imports resolve without a build step: 
"paths": {
  "smithers-orchestrator": ["./packages/smithers/src/index.js"],
  "smithers-orchestrator/jsx-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/jsx-dev-runtime": ["./packages/smithers/src/jsx-runtime.js"],
  "smithers-orchestrator/tools": ["./packages/smithers/src/tools.js"],
  "smithers-orchestrator/*": [
    "./packages/smithers/src/*.js",
    "./packages/smithers/src/*/index.js"
  ],
  "smithers-orchestrator/scorers": ["./packages/scorers/src/index.js"]
}
The root package is a private smithers-monorepo; smithers-orchestrator resolves to packages/smithers. End users do not need path aliases — only framework developers do. Installing smithers-orchestrator as a dependency lets Node/Bun module resolution handle import paths automatically.

​
Local Type Root Shims

"typeRoots": ["./src/types", "./node_modules/@types"]
The ./src/types directory contains ambient type declarations that fill gaps in third-party packages. One shim ships today:
  • react-dom-server.d.ts — Declares the react-dom/server module so TypeScript doesn’t error when server-side rendering types are referenced.
End users should add @types/react-dom to devDependencies instead of relying on this shim.

​
Bun Configuration

​
Runtime Preload

# bunfig.toml
preload = ["./preload.ts"]
The preload script registers the MDX esbuild plugin with Bun’s bundler so .mdx files can be imported as JSX components at runtime. See MDX Prompts for details.

​
Test Configuration

[test]
root = "./tests"
preload = ["./preload.ts"]
KeyValuePurpose
root./testsBun discovers test files from this directory instead of scanning the entire project
preload["./preload.ts"]Registers the MDX plugin for test files so .mdx imports work in tests
The test preload is separate from the runtime preload. Both point to the same file, but Bun’s [test] section only applies when running bun test. Without it, tests that import .mdx files fail with a module resolution error.

​
npm Scripts

Defined in the root package.json for development:
ScriptCommandPurpose
typechecktsc --noEmitType-check the src/ and tests/ trees against tsconfig.json
typecheck:examplestsc -p examples/tsconfig.json --noEmitType-check example files against a separate config that maps smithers-orchestrator to examples-entry.js
lintoxlint ...Lint source, test, and CLI code with oxlint
testbash ./scripts/run-all-tests.shRun the full test suite
e2eplaywright testRun Playwright end-to-end tests against the docs site and integration surfaces
docscd docs && bunx mintlify devStart the Mintlify docs dev server for local preview

​
For end-user projects

When scaffolding your own project (with smithers init or manually), add a typecheck script: 
{
  "scripts": {
    "typecheck": "tsc --noEmit"
  }
}
See Production Project Structure for a complete user-project package.json example.