Code Editor
Drop a Monaco editor with full IntelliSense for circuit source into your own app, and turn that source into a live simulation.
@simten/react/code-editor is the Monaco editor that powers simten.dev/circuit, packaged for your own apps. It gives circuit source typed completions and hovers for the Simten stdlib, plus automatic type acquisition so third-party imports (react, zod, …) resolve to real types instead of any.
It knows nothing about simulations. Pair it with useSimulation from @simten/react and you have the whole "editor with a live circuit next to it" experience.
pnpm add @simten/react @monaco-editor/react@monaco-editor/react and monaco-editor are optional peers: only this entry needs them, so @simten/react itself stays Monaco-free. pnpm (v8+) and npm (v7+) install peers automatically, so that one command is usually enough. Monaco itself is loaded from a CDN at runtime, not bundled.
Quick start
import { CodeEditor } from '@simten/react/code-editor';
<CodeEditor value={source} onChange={setSource} />;That's the whole setup. Compiler options, the virtual node_modules tree, the file:/// model URI, diagnostics, and type acquisition are all configured for you.
What you get
| Capability | How |
|---|---|
| Typed completions for the Simten stdlib | The @simten/core type payloads are inlined: no import, works offline |
| Types for third-party imports | @typescript/ata fetches .d.ts from jsDelivr at runtime, same as the TypeScript playground |
| Error squiggles | The diagnostics prop (see below) |
| Simten editor themes | registerSimtenThemes + the SIMTEN_DARK / SIMTEN_LIGHT constants |
CodeEditor accepts every @monaco-editor/react prop (value, defaultValue, onChange, onMount, options, …) plus the Simten-specific ones below.
Diagnostics
Pass a monaco-free list of diagnostics; the editor renders them as squiggles. You never import monaco-editor to show an error.
<CodeEditor
value={source}
onChange={setSource}
diagnostics={[{ message: 'Cannot find name "foo"', line: 3, column: 12 }]}
/>;A diagnostic with line < 1 (a whole-file error) still carries a message for your own error panel but produces no squiggle.
Themes
import { CodeEditor, registerSimtenThemes, SIMTEN_DARK, SIMTEN_LIGHT } from '@simten/react/code-editor';
<CodeEditor
value={source}
onChange={setSource}
theme={dark ? SIMTEN_DARK : SIMTEN_LIGHT}
beforeMount={(monaco) => registerSimtenThemes(monaco)}
/>;Register from beforeMount so the theme exists at first paint. Pass { lightBackground: '#faf9f4' } to tint the light theme's background to match a warm page.
Imperative handle
The ref exposes getEditor(), getMonaco(), getValue(), and setValue(), useful for loading an example or reading the source for a share link.
const editor = useRef<CodeEditorHandle>(null);
// …
editor.current?.setValue(example.code);Source → live circuit
The editor produces a string. To turn that string into a running simulation, use useSimulation from @simten/react. User code compiles and runs in the sandbox iframe, never the main frame. Every simulation on the page shares one sandbox, created when the first one needs it.
useSimulation
Source in, a running simulation out. Wiring the editor to it is the diagnostics line.
import { CircuitCanvas, ClockControls, useSimulation } from '@simten/react';
import { CodeEditor } from '@simten/react/code-editor';
function Playground() {
const [source, setSource] = useState(SEED);
const sim = useSimulation({ source });
const { compileError } = sim.state;
return (
<div className="split">
<CodeEditor
value={source}
onChange={setSource}
diagnostics={compileError ? [compileError] : []}
/>
<CircuitCanvas simulation={sim} />
<ClockControls simulation={sim} />
</div>
);
}It recompiles 50 ms after the source stops changing (the first compile goes at once), keeps the last good circuit running when a compile fails, and simulates the last circuit the source builds. Pass circuit to choose another, by name or with a function over the compiled circuits:
useSimulation({ source, circuit: 'FullAdder' });| Returns | |
|---|---|
state | ready, error, compileError (the last compile's error, with line and column when it has a location; pass it to CodeEditor's diagnostics), outputs, cycle, portValues, isRunning, speed, history, and circuits (every circuit the compile built) |
actions | set, toggle, tick, run, pause, reset, restart, stepBack, stepForward, seek, scan, sample, exportVerilog, recompile |
actions keeps one identity for the life of the component, so it's safe in dependency arrays. recompile() compiles now, skipping the debounce. With source text, the keys set takes are checked when the call reaches the sandbox, as there's no circuit to type them from until it compiles.
Compiling without simulating
To compile once and read the result, ask the sandbox client directly:
import { useSandboxClient } from '@simten/react';
const sandbox = useSandboxClient();
useEffect(() => {
if (!sandbox) return;
sandbox.compile(source).then((compiled) => {
// compiled.circuits, compiled.libraryCircuits, compiled.definitions
sandbox.release(compiled);
});
}, [sandbox, source]);Outside React, SandboxClient from @simten/sandbox does the same.
Owning your own Monaco
If you already have a Monaco instance (a collaborative editor with a Yjs binding, say, whose source of truth is a Y.Text rather than a value/onChange), use the headless primitives and keep your own <Editor>:
import { setupSimtenIntellisense, useTypeAcquisition } from '@simten/react/code-editor';
useTypeAcquisition(source, monaco); // resolves third-party imports
<Editor
path="file:///circuit.ts" // required, see below
beforeMount={setupSimtenIntellisense}
onMount={(editor) => bindYjs(editor)}
/>;CodeEditor is a thin wrapper over exactly these two.
The model must have a real file:/// URI. TypeScript resolves modules by walking up from the containing file looking for node_modules, and Monaco's default inmemory:// scheme has nothing to walk. Get this wrong and every import silently resolves to any. CodeEditor sets file:///circuit.ts for you.
Types vs execution
This entry handles types only. Circuit source executes in the sandbox iframe, which resolves imports independently. The two halves never talk: code can run while its types are still loading, and an import with no published types still runs. That's why module-not-found diagnostics are suppressed while semantic validation stays on: a red squiggle on a line that works is worse than a missing completion.
Type acquisition fetches from jsDelivr at runtime. Pass typeAcquisition={{ enabled: false }} to opt out, or { typescriptCdn } to self-host; every failure degrades to "no completions", never a broken editor.