sdk/apps/cli/.agents/skills/opentui/references/solid/gotchas.md
process.exit() directlyThis is the most common mistake. Using process.exit() leaves the terminal in a broken state (cursor hidden, raw mode, alternate screen).
// WRONG - Terminal left in broken state
process.exit(0)
// CORRECT - Use renderer.destroy()
import { useRenderer } from "@opentui/solid"
function App() {
const renderer = useRenderer()
const handleExit = () => {
renderer.destroy() // Cleans up and exits properly
}
}
renderer.destroy() restores the terminal (exits alternate screen, restores cursor, etc.) before exiting.
Symptom: JSX syntax errors, components not rendering
SyntaxError: Unexpected token '<'
Fix: Create bunfig.toml in project root:
preload = ["@opentui/solid/preload"]
Symptom: JSX compiles to React, errors about React not found
Fix: Ensure tsconfig.json has:
{
"compilerOptions": {
"jsx": "preserve",
"jsxImportSource": "@opentui/solid"
}
}
Symptom: Built bundle has raw JSX
Fix: Add Solid plugin to build:
import solidPlugin from "@opentui/solid/bun-plugin"
await Bun.build({
// ...
plugins: [solidPlugin],
})
Symptom: Value never updates, shows [Function]
// WRONG - Missing ()
const [count, setCount] = createSignal(0)
<text>Count: {count}</text> // Shows [Function]
// CORRECT
<text>Count: {count()}</text>
Symptom: Props stop being reactive
// WRONG - Breaks reactivity
function Component(props: { value: number }) {
const { value } = props // Destructured once, never updates!
return <text>{value}</text>
}
// CORRECT - Keep props reactive
function Component(props: { value: number }) {
return <text>{props.value}</text>
}
// OR use splitProps
function Component(props: { value: number; other: string }) {
const [local, rest] = splitProps(props, ["value"])
return <text>{local.value}</text>
}
Symptom: createEffect doesn't trigger
// WRONG - Signal not accessed in effect
const [count, setCount] = createSignal(0)
createEffect(() => {
console.log("Count changed") // Never runs after initial!
})
// CORRECT - Access the signal
createEffect(() => {
console.log("Count:", count()) // Runs when count changes
})
Solid's reconciler automatically decodes HTML entities in JSX text content. This means <, >, &, etc. render as their literal characters:
// These render correctly in Solid
<text>Use <box> for containers</text> // Displays: Use <box> for containers
<text>A & B</text> // Displays: A & B
This applies to text nodes, the content prop, and the text prop.
Solid uses underscores for multi-word component names:
// WRONG - React-style naming
<tab-select /> // Error!
<ascii-font /> // Error!
<line-number /> // Error!
// CORRECT - Solid naming
<tab_select />
<ascii_font />
<line_number />
Component mapping:
| Concept | React | Solid |
|---|---|---|
| Tab Select | <tab-select> | <tab_select> |
| ASCII Font | <ascii-font> | <ascii_font> |
| Line Number | <line-number> | <line_number> |
Components need explicit focus:
// WRONG
<input placeholder="Type here..." />
// CORRECT
<input placeholder="Type here..." focused />
// WRONG
<select options={["a", "b"]} />
// CORRECT
<select
options={[
{ name: "A", description: "Option A", value: "a" },
{ name: "B", description: "Option B", value: "b" },
]}
onSelect={(index, option) => {
// Called when Enter is pressed
console.log("Selected:", option.name)
}}
focused
/>
Remember: onSelect fires on Enter (selection confirmed), onChange fires on navigation:
// WRONG - expecting onChange to fire on Enter
<select
options={options()}
onChange={(i, opt) => submitForm(opt)} // This fires on arrow keys!
/>
// CORRECT
<select
options={options()}
onSelect={(i, opt) => submitForm(opt)} // Enter pressed - submit
onChange={(i, opt) => showPreview(opt)} // Arrow keys - preview
/>
Use For for arrays of objects, Index for primitives:
// For objects - item is reactive
<For each={objects()}>
{(obj) => <text>{obj.name}</text>}
</For>
// For primitives - use Index, item() is reactive
<Index each={strings()}>
{(str, index) => <text>{index}: {str()}</text>}
</Index>
Show requires fallback for proper rendering:
// May cause issues
<Show when={data()}>
<Component />
</Show>
// Better - explicit fallback
<Show when={data()} fallback={<text>Loading...</text>}>
<Component />
</Show>
Symptom: Memory leaks, multiple intervals running
// WRONG - Interval never cleared
function Timer() {
const [time, setTime] = createSignal(0)
setInterval(() => setTime(t => t + 1), 1000)
return <text>{time()}</text>
}
// CORRECT
function Timer() {
const [time, setTime] = createSignal(0)
const interval = setInterval(() => setTime(t => t + 1), 1000)
onCleanup(() => clearInterval(interval))
return <text>{time()}</text>
}
createEffect(() => {
const subscription = subscribe(data())
// WRONG - No cleanup
// subscription stays active
// CORRECT
onCleanup(() => subscription.unsubscribe())
})
Symptom: Changes don't trigger updates
const [state, setState] = createStore({ items: [] })
// WRONG - Direct mutation
state.items.push(newItem) // Won't trigger updates!
// CORRECT - Use setState
setState("items", items => [...items, newItem])
const [state, setState] = createStore({
user: { profile: { name: "John" } }
})
// WRONG
state.user.profile.name = "Jane"
// CORRECT
setState("user", "profile", "name", "Jane")
OpenTUI captures console output:
import { useRenderer } from "@opentui/solid"
import { onMount } from "solid-js"
function App() {
const renderer = useRenderer()
onMount(() => {
renderer.console.show()
console.log("Now visible!")
})
return <box></box>
}
Use createEffect to debug:
createEffect(() => {
console.log("State:", {
count: count(),
items: items(),
})
})
# WRONG
node src/index.tsx
npm run start
# CORRECT
bun run src/index.tsx
bun run start
The render function is async when creating a renderer:
// This is fine - Bun supports top-level await
render(() => <App />)
// If you need the renderer
import { createCliRenderer } from "@opentui/core"
import { render } from "@opentui/solid"
const renderer = await createCliRenderer()
render(() => <App />, renderer)
Usually a missing reactive access:
// Check if signal is being called
<text>{count()}</text> // Note the ()
// Check if props are being accessed correctly
<text>{props.value}</text> // Not destructured
Check component naming:
// Wrong
<tab-select></tab-select>
// Correct
<tab_select></tab_select>
Stores aren't called like signals:
const [store, setStore] = createStore({ count: 0 })
// WRONG
<text>{store().count}</text>
// CORRECT
<text>{store.count}</text>