> ## Documentation Index > Fetch the complete documentation index at: https://smithers-feat-claude-workflow-mirror.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Package Configuration > Reference for the smithers-orchestrator package exports, TypeScript configuration, and Bun preload setup. This page covers: CLI binary usage, subpath export map, TypeScript compiler options, Bun preload and test config, and npm scripts. ## Binary Use `bunx smithers-orchestrator ` 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. Entry files in this table are relative to the published `smithers-orchestrator` package; in the repository they live under `packages/smithers/`. | Import path | Entry file | Purpose | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------- | | `smithers-orchestrator` | `./src/index.js` | Core API: `createSmithers`, `openSmithersBackend`, components, `runWorkflow`, `renderMdx`, errors | | `smithers-orchestrator/gateway` | `./src/gateway.js` | Gateway server primitives from `@smithers-orchestrator/server/gateway` | | `smithers-orchestrator/gateway-client` | `./src/gateway-client.js` | Typed client helpers from `@smithers-orchestrator/gateway-client` | | `smithers-orchestrator/gateway-react` | `./src/gateway-react.js` | React hooks and providers for gateway-backed UIs | | `smithers-orchestrator/sandbox` | `./src/sandbox.js` | Sandbox provider contracts, bundles, and execution helpers | | `smithers-orchestrator/jsx-runtime` | `./src/jsx-runtime.js` | JSX runtime (auto-resolved by `jsxImportSource`) | | `smithers-orchestrator/jsx-dev-runtime` | `./src/jsx-runtime.js` | JSX dev runtime (auto-resolved in dev mode) | | `smithers-orchestrator/tools` | `./src/tools.js` | Tool sandbox: `defineTool`, `read`, `grep`, `bash`, `edit`, `write` | | `smithers-orchestrator/server` | `./src/server.js` | HTTP server for run management and event streaming | | `smithers-orchestrator/observability` | `./src/observability.js` | OpenTelemetry traces, metrics, and Prometheus integration | | `smithers-orchestrator/mdx-plugin` | `./src/mdx-plugin.js` | Bun preload plugin for `.mdx` imports | | `smithers-orchestrator/dom/renderer` | `./src/dom/renderer.js` | Internal renderer (advanced use) | | `smithers-orchestrator/serve` | `./src/serve.js` | Single-workflow HTTP server via `createServeApp` | | `smithers-orchestrator/scorers` | `./src/scorers.js` | Eval scorers: `createScorer`, `llmJudge`, `aggregateScores` | | `smithers-orchestrator/memory` | `./src/memory.js` | Cross-run facts, message history, processors, and metrics | | `smithers-orchestrator/openapi` | `./src/openapi.js` | Generate AI SDK tools from OpenAPI specs | | `smithers-orchestrator/control-plane` | `./src/control-plane.js` | Organization, project, billing, usage, secret-reference, and audit primitives | | `smithers-orchestrator/*` | `./src/*.js` | Wildcard-backed facade wrappers for additional public subpaths | The PI plugin is published as the separate `@smithers-orchestrator/pi-plugin` package. The old `smithers-orchestrator/pi-plugin` and `smithers-orchestrator/pi-extension` subpaths are no longer exported. ## Workspace Packages Most applications should import from `smithers-orchestrator`. The workspace packages below are listed for advanced integrations, custom clients, framework development, and monorepo orientation. Some app workspaces are private and are not published packages. | Package | Primary surface | Related docs | | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `smithers-orchestrator` | Public facade for workflow authoring, components, agents, tools, server helpers, memory, OpenAPI tools, scorers, and JSX runtime setup | This page, [Types](/reference/types) | | `@smithers-orchestrator/cli` | CLI entrypoint, MCP server, local workflow pack, account registry commands, DevTools commands, cron, alerts, and server commands | [CLI Overview](/cli/overview), [MCP Server](/integrations/mcp-server) | | `@smithers-orchestrator/accounts` | Subscription and API-key account registry helpers: `listAccounts`, `addAccount`, `removeAccount`, `getAccount`, `accountToProviderEnv` | [CLI Agents](/integrations/cli-agents) | | `@smithers-orchestrator/agents` | AI SDK and CLI agent adapters, CLI capability reports, agent contracts, and tool capability registry | [CLI Agents](/integrations/cli-agents), [SDK Agents](/integrations/sdk-agents) | | `@smithers-orchestrator/components` | JSX workflow components such as `Task`, `Workflow`, `Approval`, `Sandbox`, `Timer`, `Signal`, and control-flow components | [Components](/how-it-works) | | `@smithers-orchestrator/control-plane` | Durable organization, project, team, billing, usage, secret-reference, and audit primitives for hosted deployments | [Control Plane](/deployment/control-plane) | | `@smithers-orchestrator/db` | SQLite/Drizzle adapter, table setup, run-state derivation, schema helpers, and output tables | [Data Model](/reference/types), [Run State](/runtime/run-state) | | `@smithers-orchestrator/devtools` | Snapshot, tree, diff, node lookup, task collection, and DevTools run-store helpers behind the CLI inspect commands | [Debugging](/guides/debugging), [CLI Overview](/cli/overview) | | `@smithers-orchestrator/driver` | Runtime driver contracts: `RunOptions`, `RunResult`, `RunStatus`, `SmithersCtx`, outputs, task runtime, interop, and child process helpers | [Run Workflow](/runtime/run-workflow), [Execution Model](/how-it-works) | | `@smithers-orchestrator/electric-proxy` | ElectricSQL shape proxy for cloud sync, scoped shape access, rate limits, stripped auth forwarding, and shape metrics | [Production Hardening](/deployment/production-hardening), [Gateway](/integrations/gateway) | | `@smithers-orchestrator/engine` | Workflow rendering/execution API: `runWorkflow`, `renderFrame`, `workflow`, `Smithers`, `fragment`, signals, and Effect versioning | [Render Frame](/runtime/render-frame), [Run Workflow](/runtime/run-workflow) | | `@smithers-orchestrator/errors` | Error definitions, known codes, JSON serialization, docs URLs, and type guards | [Errors](/reference/errors) | | `@smithers-orchestrator/gateway` | Stable Gateway RPC contracts, auth scopes, deployment metadata, and generated OpenAPI schema | [Gateway](/integrations/gateway), [RPC](/rpc/launch-run) | | `@smithers-orchestrator/gateway-client` | Browser/client SDK for Gateway RPC requests and event streams | [Gateway](/integrations/gateway) | | `@smithers-orchestrator/gateway-react` | React hooks and root helpers for Gateway-backed UIs | [Gateway](/integrations/gateway) | | `@smithers-orchestrator/graph` | Framework-neutral workflow graph model, XML nodes, task descriptors, and graph snapshots | [Planner Internals](/how-it-works), [Types](/reference/types) | | `@smithers-orchestrator/jj-darwin-arm64` | Vendored jj (Jujutsu) binary for darwin-arm64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly | [VCS Guide](/guides/vcs) | | `@smithers-orchestrator/jj-darwin-x64` | Vendored jj (Jujutsu) binary for darwin-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly | [VCS Guide](/guides/vcs) | | `@smithers-orchestrator/jj-linux-arm64` | Vendored jj (Jujutsu) binary for linux-arm64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly | [VCS Guide](/guides/vcs) | | `@smithers-orchestrator/jj-linux-x64` | Vendored jj (Jujutsu) binary for linux-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly | [VCS Guide](/guides/vcs) | | `@smithers-orchestrator/jj-win32-x64` | Vendored jj (Jujutsu) binary for win32-x64; auto-installed as an optional dependency of `@smithers-orchestrator/vcs`, not depended on directly | [VCS Guide](/guides/vcs) | | `@smithers-orchestrator/memory` | Cross-run facts, message history, processors, namespaces, service layer, and metrics | [Memory](/how-it-works), [Memory Quickstart](/guides/memory-quickstart) | | `@smithers-orchestrator/observability` | Event types, logging, tracing, metrics, Prometheus rendering, and runtime observability layers | [Events](/runtime/events), [Event Types](/reference/event-types) | | `@smithers-orchestrator/openapi` | OpenAPI parsing, operation extraction, AI SDK tool generation, schema conversion, and metrics | [OpenAPI Tools](/concepts/openapi-tools), [Tools](/integrations/tools) | | `@smithers-orchestrator/pi-plugin` | PI extension runtime, views, API wrappers, and workflow inspection integration | [PI Integration](/integrations/pi-integration) | | `@smithers-orchestrator/protocol` | Shared contracts, small value types, and protocol-level errors for cross-package use | [Types](/reference/types), [Errors](/reference/errors) | | `@smithers-orchestrator/react-reconciler` | Custom React reconciler, host context, DOM renderer, DevTools preload, driver, and JSX runtime internals | [Why React](/why-react), [Render Frame](/runtime/render-frame) | | `@smithers-orchestrator/review` | Private code review app: review flow plus story-form HTML walkthrough, exposed through the `smithers-review` bin | [CLI Overview](/cli/overview) | | `@smithers-orchestrator/sandbox` | Sandbox bundle, execute, and transport primitives used by the `Sandbox` component | [Sandbox](/components/sandbox) | | `@smithers-orchestrator/scheduler` | Pure workflow state machine: task state, scheduler decisions, retry/cache policies, wait reasons, and workflow session services | [Workflow State](/how-it-works), [Suspend and Resume](/how-it-works) | | `@smithers-orchestrator/scorers` | Scorer definitions, LLM judges, batch execution, aggregation, persistence schema, and metrics | [Evals](/guides/evals-quickstart), [Evals Quickstart](/guides/evals-quickstart) | | `@smithers-orchestrator/server` | HTTP, WebSocket, Gateway, cron, webhook, metrics, and single-workflow serving APIs | [Server](/integrations/server), [Serve](/integrations/serve) | | `@smithers-orchestrator/time-travel` | Snapshots, diffs, forks, replay, timelines, VCS tags, rewind locks/audits, and time-travel metrics | [Time Travel](/recipes), [Time Travel Quickstart](/guides/time-travel-quickstart) | | `@smithers-orchestrator/tool-context` | AsyncLocalStorage tool-execution context (run/node/idempotency keys, durability snapshot hook) shared by the engine and `smithers-orchestrator` without a dependency cycle | [Execution Model](/how-it-works) | | `@smithers-orchestrator/usage` | Account quota and rate-limit usage reporting for Smithers providers | [CLI Overview](/cli/overview) | | `@smithers-orchestrator/vcs` | VCS discovery and jj workspace operations such as `runJj`, `workspaceAdd`, `workspaceList`, and pointer reverts | [VCS Helpers](/reference/vcs-helpers), [VCS Guide](/guides/vcs) | ### Usage ```ts theme={null} // Core API import { createSmithers, openSmithersBackend, 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.js) import { mdxPlugin } from "smithers-orchestrator/mdx-plugin"; // Control-plane primitives import { ControlPlaneStore } from "smithers-orchestrator/control-plane"; ``` ## TypeScript Configuration ### JSX Import Source ```json theme={null} { "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](/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: ```jsonc theme={null} "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"], "@smithers-orchestrator/agents": ["./packages/agents/src/index.js"], "@smithers-orchestrator/gateway-client": ["./packages/gateway-client/src/index.ts"], "@smithers-orchestrator/gateway-react": ["./packages/gateway-react/src/index.ts"], "@smithers-orchestrator/pi-plugin": ["./packages/pi-plugin/src/index.ts"], "@smithers-orchestrator/server": ["./packages/server/src/index.js"] // The root tsconfig includes the same style of alias for each workspace package. } ``` 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 ```json theme={null} "typeRoots": ["./packages/smithers/src/types", "./node_modules/@types"] ``` The `./packages/smithers/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 ```toml theme={null} # bunfig.toml preload = ["./preload.js"] ``` 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](/guides/mdx-prompts) for details. ### Test Configuration ```toml theme={null} [test] root = "." preload = ["./preload.js"] ``` | Key | Value | Purpose | | --------- | ------------------ | ----------------------------------------------------------------------- | | `root` | `.` | Bun discovers test files from the repository root | | `preload` | `["./preload.js"]` | 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: | Script | Command | Purpose | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `typecheck` | `tsc --noEmit` | Type-check the `src/` and `tests/` trees against `tsconfig.json` | | `typecheck:examples` | `tsc -p examples/tsconfig.json --noEmit` | Type-check example files against a separate config that maps `smithers-orchestrator` to `examples-entry.js` | | `typecheck:evals` | `tsc -p evals/tsconfig.json --noEmit` | Type-check the agent-fluency eval suite under `evals/` against its own config | | `lint` | `oxlint --react-plugin --node-plugin --import-plugin --ignore-path .gitignore -A react/no-children-prop -A unicorn/no-thenable --ignore-pattern 'packages/*/src/**/*.d.ts' packages/*/src packages/*/tests` | Lint package source and tests with oxlint | | `lint:fix` | `oxlint --react-plugin --node-plugin --import-plugin --ignore-path .gitignore -A react/no-children-prop -A unicorn/no-thenable --ignore-pattern 'packages/*/src/**/*.d.ts' --fix --fix-suggestions packages/*/src packages/*/tests` | Apply supported oxlint fixes | | `cli` | `bun run apps/cli/src/index.js` | Run the local development CLI entrypoint | | `generate:init-pack` | `bun scripts/generate-workflow-pack.ts` | Regenerate the local workflow pack used by `bunx smithers-orchestrator init` | | `test` | `node scripts/check-single-effect-version.mjs && node scripts/check-dependency-boundaries.mjs && node scripts/check-docs.mjs && node scripts/check-llms.mjs && node scripts/check-smithers-test-script.mjs && pnpm -r --no-bail test` | Run docs/config guards, dependency guards, llms guards, and each package test script (no-bail so every failing package is reported) | | `coverage` | `node scripts/coverage.mjs` | Generate a test coverage report across the workspace | | `check:effect` | `node scripts/check-single-effect-version.mjs` | Verify the workspace resolves a single Effect version | | `check:deps` | `node scripts/check-dependency-boundaries.mjs` | Verify package dependency boundaries | | `check:docs` | `node scripts/check-docs.mjs` | Verify documentation style and API drift guards | | `check:llms` | `node scripts/check-llms.mjs` | Verify generated llms docs are current | | `fetch:jj` | `node scripts/fetch-jj-binaries.mjs` | Fetch vendored jj binaries for supported platforms | | `docs:components` | `node scripts/generate-component-source.mjs` | Embed composite component source as tabs in their docs pages | | `docs:llms` | `bun scripts/generate-llms.ts && bun scripts/optimize-llms-full.ts` | Regenerate `llms-core.txt` and `llms-full.txt` | | `docs` | `cd docs && bunx mintlify dev` | Start the Mintlify docs dev server for local preview | | `release:content` | `bunx smithers-orchestrator up .smithers/workflows/release-content.tsx` | Run the release-content workflow (changelog, tweet thread, blog) in dry-run mode | | `release:content:approve` | `bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":false}'` | Generate release content for real but stop before publishing | | `release:content:publish` | `bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true}'` | Generate and publish the release content | | `release:workflow` | `bunx smithers-orchestrator up .smithers/workflows/release.tsx` | Run the end-to-end release workflow | | `release:workflow:gated` | `bunx smithers-orchestrator up .smithers/workflows/release.tsx --input '{"requireMarketingContent":true}'` | Run the release workflow but require marketing content before publishing | | `marketing:thread` | `bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'` | Generate just the tweet thread in dry-run mode, skipping changelog and blog | | `marketing:thread:write` | `bunx smithers-orchestrator up .smithers/workflows/release-content.tsx --input '{"dryRun":false,"publish":true,"allowUnreviewedPublish":true,"channels":{"changelog":false,"tweetThread":true,"blogPost":false},"skip":{"changelog":true,"blogPost":true,"approval":true,"publishX":true,"publishBlog":true,"publishChangelog":true}}'` | Generate and publish just the tweet thread, skipping changelog, blog, and the approval gate | | `version` | `node scripts/bump.mjs` | Bump package versions using the release helper | | `release` | `node scripts/publish.mjs` | Publish packages using the release helper | | `sandbox:up` | `bun scripts/sandbox.ts up` | Create a disposable GCP sandbox VM and open an SSH session into it | | `sandbox:down` | `bun scripts/sandbox.ts down` | Delete the sandbox VM created by `sandbox:up` | ### For end-user projects When scaffolding your own project (with `bunx smithers-orchestrator init` or manually), add a typecheck script: ```json theme={null} { "scripts": { "typecheck": "tsc --noEmit" } } ``` See [Production Project Structure](/guides/project-structure) for a complete user-project `package.json` example.