Artifact System
Relevant source files
The following files were used as context for generating this wiki page:
The Artifact System is a core architectural component of the Bolt application designed to manage structured, actionable content generated by the AI assistant. It provides a mechanism to encapsulate code generation, file system modifications, and shell command executions within discrete containers called "Artifacts." These artifacts are parsed from the assistant's streaming response and integrated into the user interface via a dedicated workbench.
By using specific XML-like tags, the system allows the assistant to propose complex changes that are decoupled from standard chat text. These changes are then handled by the WorkbenchStore, which coordinates with the WebContainer API to execute actions such as creating files or running terminal commands.
Sources: app/lib/runtime/message-parser.ts:7-13, app/lib/stores/workbench.ts:25-45, app/lib/hooks/useMessageParser.ts:11-30
Architecture and Data Flow
The system operates as a pipeline starting from raw text input and ending with state updates in the global stores. The process is primarily driven by the StreamingMessageParser, which identifies artifact boundaries in real-time as chunks arrive from the AI model.
Execution Flow Diagram
The following diagram illustrates how a message containing an artifact is processed from the moment it is received until it is rendered in the UI and executed in the workbench.
Core Components
1. Streaming Message Parser
The StreamingMessageParser is a stateful utility that scans incoming text for specific tags: <boltArtifact> and <boltAction>. It uses a pointer-based approach to handle partial chunks, ensuring that tags split across multiple stream packets are correctly reassembled and validated.
- Artifact Tags:
<boltArtifact title="..." id="..."> - Action Tags:
<boltAction type="file" filePath="...">or<boltAction type="shell">
Sources: app/lib/runtime/message-parser.ts:7-13, app/lib/runtime/message-parser.ts:50-58
2. Workbench Store
The WorkbenchStore acts as the orchestrator for all active artifacts. It maintains a registry of artifacts indexed by messageId and manages the lifecycle of ActionRunner instances associated with each artifact.
| Field | Type | Description |
|---|---|---|
artifacts | MapStore<Record<string, ArtifactState>> | A reactive map of active artifacts and their execution runners. |
artifactIdList | string[] | An ordered list of artifact IDs for UI sequencing. |
showWorkbench | WritableAtom<boolean> | Controls the visibility of the side-panel workbench. |
Sources: app/lib/stores/workbench.ts:25-45
3. Artifact UI Component
The Artifact React component is responsible for rendering the visual representation of an artifact within the chat message. It displays the artifact title, provides a button to open the workbench, and lists the status of all associated actions (e.g., pending, running, complete, or failed).
Sources: app/components/chat/Artifact.tsx:32-75
Action Handling
Artifacts contain "Actions," which represent the actual work to be performed. Actions are categorized by their type attribute.
Action Types and Metadata
| Action Type | Key Attributes | Purpose |
|---|---|---|
file | filePath | Creates or updates a file at the specified path within the WebContainer filesystem. |
shell | N/A | Executes a command string in the integrated terminal. |
Sources: app/lib/runtime/message-parser.ts:187-205
Action Lifecycle Sequence
The sequence below shows how an action within an artifact is handled once the parser detects its closing tag.
Integration with Markdown
Artifacts are integrated into the markdown rendering pipeline. The Markdown component utilizes a custom div renderer to detect elements marked with the __boltArtifact__ class (injected by the parser) and replaces them with the interactive Artifact React component.
// Example of the parser generating the anchor element
const createArtifactElement: ElementFactory = (props) => {
const elementProps = [
'class="__boltArtifact__"',
...Object.entries(props).map(([key, value]) => {
return `data-${camelToDashCase(key)}=${JSON.stringify(value)}`;
}),
];
return `<div ${elementProps.join(' ')}></div>`;
};
Sources: app/lib/runtime/message-parser.ts:217-227, app/components/chat/Markdown.tsx:26-38
Summary
The Artifact System enables a seamless transition from AI conversation to technical execution. By parsing structured tags from streaming text, the system populates the WorkbenchStore, which in turn manages the execution of file operations and shell commands via WebContainers. This architecture ensures that the AI can perform complex software engineering tasks while providing the user with clear, real-time feedback on the status of each operation.