Sandpack React

Sandpack React is the component layer of CodeSandbox’s Sandpack toolkit, giving developers headless, composable React building blocks — SandpackProvider, SandpackCodeEditor, SandpackPreview, SandpackConsole, and SandpackTests — for embedding editable, runnable code sandboxes directly inside a web app. Rather than dropping in a single opaque iframe, it exposes primitives and hooks (useSandpack, useActiveCode, useSandpackTheme) so teams can assemble their own editor layouts, swap CodeMirror language extensions, and theme the whole experience with Stitches-based tokens.

Under the hood it sits on @codesandbox/sandpack-client, which bridges a React app and an in-browser bundler running in a sandboxed iframe over postMessage, and ships prebuilt templates for React, Vue, Angular, Svelte, vanilla JS, and Node.js so consumers can spin up a working sandbox in one line. It’s used heavily in documentation sites, interactive tutorials, and internal playground tools that need live, editable code samples without shipping users off to an external sandbox site.

What You Get

• Preset <Sandpack> component for a ready-made editor + preview layout in one line
• Granular components (SandpackCodeEditor, SandpackPreview, SandpackConsole, SandpackTests, SandpackFileExplorer) for fully custom layouts
• React hooks (useSandpack, useActiveCode, useSandpackNavigation, useSandpackTheme) for reading and controlling sandbox state
• Built-in templates for React, Vue, Angular, Svelte, vanilla JS/TS, and Node.js starting points
• CodeMirror 6-powered editor with syntax highlighting, autocomplete, and inline error reporting
• Theme system built on Stitches for matching sandbox styling to a host app’s design

Common Use Cases

• Embedding interactive, runnable code samples in documentation sites and API references
• Building coding-focused tutorials or courses where readers edit and run snippets inline
• Powering internal component/playground tools for design systems and component libraries
• Letting users submit runnable code as part of support tickets, bug reports, or take-home tests
• Prototyping small multi-file apps entirely client-side without a backend build step

Under The Hood

Architecture Sandpack React is built around a single context provider, SandpackProvider (src/contexts/sandpackContext.tsx), which composes three internal hooks — useFiles, useClient, and useAppState — and exposes their combined state and operations through React context. Every consumer, from the bundled <Sandpack> preset (src/presets/Sandpack.tsx) down to granular pieces like SandpackCodeEditor, SandpackPreview, SandpackConsole, and SandpackTests, reads and mutates this shared state via the useSandpack hook rather than through props, making the library genuinely headless: the preset component is just one possible layout built from the same primitives a consumer could recompose themselves. Sandbox templates are resolved through a SANDBOX_TEMPLATES lookup keyed by a template prop, and actual code execution is delegated to the separate @codesandbox/sandpack-client package, which manages an iframe-based bundler over postMessage — so this package’s own responsibility stays scoped to React state and UI, with bundling/runtime concerns pushed to a lower layer. The main risk surface is the <Sandpack> preset itself, which mixes resizable-panel drag logic, layout mode switching, and console visibility state in one component; changing the underlying context shape would ripple through every consumer since there is no intermediate selector layer.

Tech Stack The package is TypeScript throughout, targeting React as a peer dependency, and built with Rollup into dual ESM/CJS output plus type declarations. The code editor is powered by CodeMirror 6 (@codemirror/view, @codemirror/language, @codemirror/autocomplete, @codemirror/lang-* packages) alongside @lezer/highlight for syntax highlighting. Styling runs through @stitches/core, a CSS-in-JS library used both for internal component styles and for the theme system (SandpackThemeProvider, bundled themes like githubLight). Supporting utilities include lz-string for compressing serialized sandbox state, anser for parsing ANSI escape codes in console output, dequal for state comparisons, and an embedded react-devtools-inline build for in-sandbox React DevTools. The monorepo (Lerna + Turborepo) also builds a companion @codesandbox/sandpack-client package that this library depends on directly, and a Storybook setup drives local development and the published component stories.

Code Quality Jest with Testing Library covers a modest set of components (14 test files under src/), including server-rendering safety tests for the <Sandpack> preset, though coverage is selective rather than exhaustive — many components and hooks have no colocated test, and at least one test case is explicitly skipped (it.skip). TypeScript runs in strict mode with declaration emission and noImplicitAny, ESLint and Prettier are configured project-wide, and GitHub Actions workflows (check-pr.yml, checks.yml) run lint, typecheck, and test on every PR alongside separate canary and stable release workflows. Naming is consistent — hooks prefixed use, components prefixed Sandpack — and error handling favors typed props and defensive defaults (e.g. options ??= {}) over thrown exceptions in the UI layer.

What Makes It Unique Where most embeddable code-sandbox products (CodeSandbox’s own iframe embed, StackBlitz WebContainers) ship as a single opaque widget, Sandpack React exposes its internals as independently usable, styleable React primitives — a genuinely headless-UI approach to sandboxed code execution. Consumers can keep the real in-browser bundler and multi-file project model while fully replacing the editor chrome, swapping in their own file explorer, or reusing the shared reactive state (file contents, active file, bundler status) to drive completely custom layouts. That combination of a real bundler backend with composable, themeable React building blocks is uncommon among comparable sandbox toolkits, most of which trade composability for a simpler all-in-one embed.