Skip to main content
The imports: block at the top of a .toon file lets you bring in external TypeScript types, Effect services, TOON components, and plugins. Import arrays use TOON’s tabular format for compact, readable declarations.

​
Importing Schemas

Import Schema.Class or Model.Class definitions for use as input or output types: 
imports:
  schemas[1]{from,use}:
    ./schemas.ts,"TicketInput,AnalysisOutput,ReviewOutput"

name: bugfix
input: TicketInput

steps[2]:
  - id: analyze
    prompt: Analyze {input.description}.
    output: AnalysisOutput

  - id: review
    prompt: Review {analyze.summary}.
    output: ReviewOutput

​
Importing Services

Import Effect services to make them available in handler: functions and run: blocks: 
imports:
  services[2]{from,use}:
    ./services/coder.ts,Coder
    ./services/jj.ts,JJ

steps[1]:
  - id: fix
    handler: ./handlers/fix.ts#applyFix
    output:
      patch: string
The imported services must be provided through the Layer stack when executing the workflow.

​
Importing Components

Import reusable components from other .toon files: 
imports:
  components[2]{from,use}:
    ./shared/review-cycle.toon,ReviewCycle
    ./shared/deploy-gate.toon,GuardedDeploy

steps[1]:
  - id: review
    kind: component
    use: ReviewCycle
    with:
      content: "{draft.content}"
      reviewer: "a tech lead"

​
Importing Other TOON Files

Import an entire .toon file as a sub-workflow: 
imports:
  workflows[1]{from,as}:
    ./sub-workflows/research.toon,research

steps[2]:
  - id: do-research
    kind: workflow
    use: research
    input:
      topic: "{input.topic}"

  - id: report
    prompt: "Write a report based on:\n{do-research.summary}"
    output:
      report: string

​
Plugin Setup

Plugins extend TOON with custom node kinds, model providers, or services. Plugins have per-entry config, so they use expanded list items: 
imports:
  plugins[2]:
    - from: smithers-plugin-anthropic
      config:
        defaultModel: claude-opus-4-6
    - from: smithers-plugin-linear
      config:
        team: ENG
Plugins are loaded at build time and can:
  • Add custom node kinds (e.g., kind: linear-ticket)
  • Provide default model configuration
  • Register services automatically into the Layer stack
  • Add custom interpolation functions

​
Import Resolution

Imports are resolved relative to the .toon file’s directory: 
project/
  workflows/
    main.toon
    shared/
      review.toon
  schemas/
    types.ts
  services/
    coder.ts
Package imports (without ./) resolve from node_modules: 
imports:
  plugins[1]:
    - from: smithers-plugin-anthropic

​
Multiple Import Sources

Combine different import types freely: 
imports:
  schemas[1]{from,use}:
    ./schemas.ts,"Input,Output"
  services[1]{from,use}:
    ./services/index.ts,"Coder,Reviewer,Deployer"
  components[1]{from,use}:
    ./shared/patterns.toon,"ReviewLoop,DeployGate"
  plugins[1]:
    - from: smithers-plugin-anthropic

​
Next Steps

  • Schemas — Define and import type definitions.
  • Components — Create and use reusable components.
  • Overview — How TOON fits into the three-layer architecture.