Migration guide v1.x

We're excited to announce a major release of Sandpack! It includes many feature requests and a ton of improvements to the developer experience. Here are a few highlights:

Improve SSR support.
Fresh design and new semantic UI tokens.
Introduce the SandpackFileExplorer component.
Improvements to the surface API.

New features

SSR support

Sandpack uses stitches/core under the hood to generate and dedupe theme variation, ensuring a consistent and lightweight CSS output. To retrieve its style values, use the following guide to get the output in the SSR:

import { getSandpackCssText } from "@codesandbox/sandpack-react";
 
// SSR template
<style
  dangerouslySetInnerHTML={{ __html: getSandpackCssText() }}
  id="sandpack"
/>;

For further clarity, take a look at our examples.

SandpackFileExplorer

We heard you, and now Sandpack has a new component to navigate through files:

export default function App() {
  return <h1>Hello world</h1>
}

Open Sandbox

Theme package

To reduce the bundle size of the main package and make it possible for the community to contribute custom Sandpack themes with ease, we have detached the themes.

So themes won't be available anymore through the @codesandbox/sandpack-react package but instead through @codesandbox/sandpack-themes.

For example:

import { Sandpack } from "@codesandbox/sandpack-react";
import { githubLight, sandpackDark } from "@codesandbox/sandpack-themes";

export default function App() {
  return (
    <Sandpack 
      theme={githubLight}
    />
  );
}

Open Sandbox

Sandpack still offers a set of predefined options:

<Sandpack
  theme="auto" // prefer color scheme sensitive
/>

But individual values can be passed to customize the style of your Sandpack instance:

import { Sandpack } from "@codesandbox/sandpack-react";
import { githubLight } from "@codesandbox/sandpack-themes";

export default function App() {
  return (
    <Sandpack 
      theme={{
        ...githubLight,
        colors: {
          accent: "rebeccapurple",
        },
        syntax: {
          tag: "#006400",
          string: "rgb(255, 165, 0)",
          plain: "tomato",
        },
      }}
    />
  );
}

Open Sandbox

Fresh design

We took this chance to rethink how Sandpack should fit on your website. Our amazing design team at CodeSandbox challenged themselves to come up with a solution that would fit in different layouts and contexts, but still be accessible and customizable.

As a result, we created a new set of themes, icons, design tokens, and components from scratch.

import "./styles.css";

document.getElementById("app").innerHTML = `
<h1>Hello world</h1>
`;

Open Sandbox

All props are type-safe

From now on, files , visibleFiles and activeFile are type-safe:

Additional highlights

New React template: supports v18.
Fix mismatch id from server to client on the SandpackCodeEditor component.
Getting ready to support a new feature to load sandboxes from CodeSandbox 👀.
Fix inconsistency between the dependencies prop and the package.json file.
SandpackProvider API: it fixes a few inconsistencies, which used to lead to very common mistakes. From now on, it's very similar to the Sandpack API, with some exceptions.
Improve error message descriptions.

Breaking changes

SandpackRunner has been deprecated because the same result can be achieved using the SandpackPreview component.
customSetup.main has been deprecated due to redundancy; use options.activeFile instead.
customSetup.files has been deprecated due to redundancy; use files instead.
options.openPaths has been deprecated; use options.visibleFiles instead.
Replaced the customStyle prop with style.
Deprecated viewportSize and viewportOrientation from the SandpackPreview component.
Deprecated theme on SandpackLayout; set the theme property on SandpackProvider instead.
SandpackLayout no longer renders ClasserProvider and SandpackThemeProvider, all context is rendered on SandpackProvider.

Migration guide

Surface API: Sandpack

// Before
<Sandpack
  customSetup={{ files: { "/src/App.vue": "" }, main: "/src/App.vue" }}
  template="vue"
/>

// Now
<Sandpack
  files={{ "/src/App.vue": "" }}
  options={{ activeFile: "/src/App.vue" }}
  template="vue"
/>

Surface API: SandpackProvider

// Before
<SandpackProvider
  activePath="/src/App.vue"
  customSetup={{ files: { "/src/App.vue": "" }, dependencies: {} }}
  template="vue"
  openPaths={["/src/App.vue"]}
/>

// Now
<SandpackProvider
  customSetup={{ dependencies: {} }}
  files={{ "/src/App.vue": "" }}
  options={{
    activeFile: "/src/App.vue", // used to be activePath
    visibleFiles: ["/src/App.vue"], // used to be openPaths
  }}
  template="vue"
/>

Surface API: common components

// Before
<SandpackStack customStyle={customStyle} />

// Now
<SandpackStack style={customStyle} />

Theme prop

// Before
<Sandpack theme="github-light" />

// Now
import { githubLight } from "@codesandbox/sandpack-themes";
 
<Sandpack theme={githubLight} />;

Theme provider

// Before
<SandpackProvider>
  <SandpackLayout theme="github-light">...</SandpackLayout>
</SandpackProvider>

// Now
<SandpackProvider theme="github-light">
  <SandpackLayout>...</SandpackLayout>
</SandpackProvider>

New theme tokens

We created a few new additional tokens and replaced some existing ones. So previous schemas might need some updates. See a list of schema changes below.

How to read: [from key name] → [to key name]

palette → colors
- activeText → hover
- defaultText → clickable
- inactiveText → surface2
- inactiveText → disabled
- defaultBackground → surface1
- new → surface3
- accent → accent
- errorForeground → error
- errorBackground → errorSurface
typography → font
- bodyFont → body
- monoFont → mono
- fontSize → size
- lineHeight → lineHeight

FAQ v2.x