@tscircuit/runframe

tscircuit ⋅ View Examples

A React component that runs tscircuit inside a webworker and shows you the PCB,
Schematic, 3D and other previews.

- Automatically imports other snippets and libraries if imported
- Runs inside webworker (doesn't block the main thread)
- Converts typescript to javascript using babel

Usage

``tsx
import { RunFrame } from "@tscircuit/runframe/runner"

const App = () => (
fsMap={{
"main.tsx":
circuit.add(

)
,
}}
entrypoint="main.tsx"

// Listen to events
onCircuitJsonChange={(circuitJson) => void}
onRenderingFinished={({ circuitJson }) => void}
onRenderEvent={(event) => void}
onError={(error) => void}
availableTabs={["pcb", "schematic", "cad"]}
defaultTab="pcb"
/>
)
`

$3

If you already have circuit JSON and just want to display it:

`tsx
import { CircuitJsonPreview } from "@tscircuit/runframe/preview"

const App = () => (
circuitJson={myCircuitJson}
// Optional props
showCodeTab={false} // Show/hide the code editor tab
showJsonTab={true} // Show/hide the raw JSON viewer tab
className="h-screen" // Container className
headerClassName="px-4" // Header className
isFullScreen={false} // Toggle fullscreen mode
onToggleFullScreen={() => void} // Fullscreen toggle callback
/>
)
`

$3

For displaying circuit JSON files that are fetched on-demand without code execution:

`tsx
import { RunFrameStaticBuildViewer } from "@tscircuit/runframe"

const App = () => (
files={[
{
filePath: "main.circuit.json",
fileStaticAssetUrl: "https://api.example.com/circuits/main.json"
},
{
filePath: "components/sensor.circuit.json",
fileStaticAssetUrl: "https://api.example.com/circuits/sensor.json"
}
]}
// Optional: Custom fetch function for authentication, caching, etc.
onFetchFile={async (fileRef) => {
const response = await fetch(fileRef.fileStaticAssetUrl, {
headers: { Authorization: 'Bearer token' }
})
return response.json()
}}
projectName="My Project"
defaultToFullScreen={false}
showToggleFullScreen={true}
/>
)
`

$3

`tsx
import evalWebWorkerBlobUrl from "@tscircuit/eval/blob-url"
`

$3

RunFrame can be embedded in an iframe, allowing you to evaluate tscircuit code from a parent application. There are two main ways to integrate RunFrame: using the React component or creating a standalone iframe implementation.

`html






id="runframe"
src="https://runframe.tscircuit.com/iframe.html"
style="width: 100%; height: 600px; border: none;"
>




`

#### Listening for events from the iframe

`tsx
window.addEventListener("message", (event) => {
if (event.data?.runframe_type === "runframe_event") {
const { type } = event.data.runframe_event
if (type === "error") {
console.error(event.data.runframe_event.error_message)
}
}
})
`

Development

$3

Edit events can be a complex to understand, because it can take some
time for rendering to complete, edit events are applied for an
approximate render before the circuit is fully rendered. The sequence
diagram below can be used as a reference to understand how the edit events
are applied and queued for rendering.

`mermaid
sequenceDiagram
participant CLI
participant FileServer as File Server
participant BrowserRunframe as Browser Runframe
participant Viewer as Schematic/PCB Viewer

BrowserRunframe->>Viewer: Initial Circuit JSON

Note over Viewer: Edit event created
Viewer->>BrowserRunframe: onEditEvent
Note over BrowserRunframe: newEditEvent._applied=false
editEvents.push(newEditEvent)
BrowserRunframe->>Viewer: editEvents={editEvents}

BrowserRunframe->>FileServer: /files/get manual-edits.json
FileServer-->>BrowserRunframe: manual-edits.json content

Note over BrowserRunframe: Apply edit events to manual-edits.json
Mark editEvent._applied = true

BrowserRunframe->>FileServer: /files/update manual-edits.json
FileServer->>CLI: FILE_UPDATED event

Note over CLI: Update manual-edits.json on filesystem

rect rgb(200, 230, 255)
Note over BrowserRunframe: Start re-render

Note over Viewer: Edit event created
Viewer->>BrowserRunframe: onEditEvent
Note over BrowserRunframe: newEditEvent._applied=false
editEvents.push(newEditEvent)
BrowserRunframe->>Viewer: editEvents={editEvents}
both unapplied & applied
edit events are sent

Note over BrowserRunframe: Render complete
end

Note over BrowserRunframe: Remove all applied editEvents

BrowserRunframe->>Viewer: editEvents={editEvents}
circuitJson={circuitJson}
Send unapplied editEvents list
+ Circuit JSON

Note over BrowserRunframe: If there are unapplied editEvents, repeat
`

$3

The event bus for the RunFrame is accessible from the @tscircuit/file-server
/events/list` endpoint. RunFrame creates the following events:

| Event Name | Description |
| ----------------------- | ------------------------------------------------------- |
| FILE_UPDATED | A file was updated |
| REQUEST_TO_SAVE_SNIPPET | Browser request to save the current circuit to snippets |
| FAILED_TO_SAVE_SNIPPET | Failed to save the current snippet to Registry |
| SNIPPET_SAVED | Snippet was saved to Registry |