# Stack Trace

Render a failed command with parsed stack frames, app frames, and collapsed framework frames.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="stack-trace-demo" title="stack-trace-demo.tsx" src="examples/stack-trace-demo.tsx" align="start" previewClassName="h-auto">
<StackTraceDemo />
</ComponentPreview>

Stack Trace renders a failed command as a collapsible trace. The error message sits at the top in destructive color, app frames are links to the file, and framework frames from `node_modules` or `node:` collapse into a monospace list.

Stack Trace is a **composition**, not a primitive. It composes [Trace](/docs/components/trace) and [Code Block](/docs/components/code-block) and streams failures through a chat transport.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
~~~bash
npx frakment add trace code-block message bubble button
~~~
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the primitives:
</Step>

~~~bash
npx frakment add trace code-block message bubble button
~~~

<Step>
Copy the demo into your project:
</Step>

<ComponentSource name="stack-trace-demo" title="examples/stack-trace-demo.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

~~~tsx title="stack-trace.tsx"
import {
  Trace,
  TraceCollapsible,
  TraceCollapsibleContent,
  TraceCollapsibleTrigger,
  TraceIcon,
  TraceLine,
  TraceTitle,
} from "@/components/ui/trace";
import { FileCodeIcon, LayersIcon, TerminalIcon } from "lucide-react";
~~~

~~~tsx title="stack-trace.tsx"
<TraceCollapsible defaultOpen>
  <TraceCollapsibleTrigger>
    <TraceLine status="error">
      <TraceIcon>
        <TerminalIcon />
      </TraceIcon>
      <TraceTitle>{`Failed: ${error}`}</TraceTitle>
    </TraceLine>
  </TraceCollapsibleTrigger>
  <TraceCollapsibleContent>
    <p className="text-destructive font-mono text-xs">{error}</p>
    <Trace>{/* frames */}</Trace>
  </TraceCollapsibleContent>
</TraceCollapsible>
~~~

## Anatomy [#anatomy]

~~~tsx title="stack-trace.tsx"
<TraceCollapsible>
  <TraceCollapsibleTrigger>
    <TraceLine status="error">
      <TraceIcon />
      <TraceTitle />
    </TraceLine>
  </TraceCollapsibleTrigger>
  <TraceCollapsibleContent>
    <p />
    <Trace>
      <a>
        <TraceLine>
          <TraceIcon />
          <TraceTitle />
        </TraceLine>
      </a>
      <TraceCollapsible>
        <TraceCollapsibleTrigger>
          <TraceLine>
            <TraceIcon />
            <TraceTitle />
          </TraceLine>
        </TraceCollapsibleTrigger>
        <TraceCollapsibleContent>
          <ol />
        </TraceCollapsibleContent>
      </TraceCollapsible>
    </Trace>
  </TraceCollapsibleContent>
</TraceCollapsible>
~~~

- **TraceCollapsibleTrigger** — the header row, marked `status="error"`
- **TraceCollapsibleContent** — the full trace block
- **Trace** — nested list of frames
- **`<a>` + TraceLine** — one app frame, links to the file and line
- **Nested TraceCollapsible** — framework frames, collapsed by default

## Parsing frames [#parsing-frames]

Split the stack into the error line and the frame lines, then parse each frame with a regex. V8 frames look like `at name (file:line:col)`. Frames from `node_modules` or `node:` are internal and collapse together.

~~~ts title="stack-trace.ts"
function parseFrame(line: string) {
  const match = line.match(/^at (.+) \((.+):(\d+):(\d+)\)$/)

  return {
    line,
    name: match?.[1],
    file: match?.[2],
    lineNumber: match?.[3],
    internal: line.includes("node_modules") || line.includes("node:"),
  }
}
~~~

## Static frames [#static-frames]

Render a fixed stack without a chat transport for a read-only summary.

<ComponentPreview name="stack-trace-frames" title="stack-trace-frames.tsx" src="examples/stack-trace-frames.tsx" align="start" previewClassName="h-auto">
<u />
</ComponentPreview>

## With command output [#with-command-output]

Successful commands render their stdout in a [Code Block](/docs/components/code-block). The failed command renders the stack trace in place. The demo alternates between the two so the transition is visible on replay.

## Accessibility [#accessibility]

- Each app frame is a link. Add `target` and `rel` if the file opens outside the app.
- The framework frames are plain text in an `<ol>`. Screen readers announce the list position.
- The error line is text, not an icon. Color is a secondary signal.
- `prefers-reduced-motion` disables collapse animation.

## Best Practices [#best-practices]

- **Show app frames first.** Framework frames are noise for most debugging.
- **Collapse the framework list.** Users only expand it when the app frame is not enough.
- **Link app frames to source.** A `#file:line` anchor is enough for local dev.
- **Pair with a plain-text summary.** The stack is evidence, not the answer.