Skip to main content

Release v1.x

Today 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 SandpackFileExplorer component;
  • Improvements in 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>
}

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 it won’t be available anymore through the @codesandbox/sandpack-react package but @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}
    />
  );
}


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",
        },
      }}
    />
  );
}

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 could 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>
<div>
  We use the same configuration as Parcel to bundle this sandbox, you can find more
  info about Parcel 
  <a href="https://parceljs.org" target="_blank" rel="noopener noreferrer">here</a>.
</div>
`;

All props are type-safe

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

Plus:

  • 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 sandbox from codesandbox.io 👀;
  • Fix inconsistency between dependencies prop and package json file;
  • SandpackProvider API: it fixes a few inconsistencies, which used to lead to very common mistakes. From now on, it's very alike to Sandpack API, except that for some exceptions;
  • Improve error message descriptions;

Breaking changes

  • SandpackRunner has been deprecated because the same result can be done 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;
  • Replace customStyle prop to style;
  • Deprecated viewportSize and viewportOrientation from SandpackPreview component;
  • Deprecated theme on SandpackLayout, set the theme property on SandpackProvider instead;
  • SandpackLayout no longer render ClasserProvider and SandpackThemeProvider, all context are 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 also replaced a few existing ones. So previous schemas might need some update. Here you’ll find a list of schema changes.

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