I've been using code playgrounds in my blog posts for a while now. They're a great way to make the content more engaging and informative.
The easiest way to do this is to embed something like CodeSandbox or StackBlitz into the post. That said, while these tools are amazing, they're not perfect. There's not much room to customize the experience per playground.
Luckily, the CodeSandbox team thought of this and released Sandpack!
Sandpack lets you build lightweight customized coding experiences.
Sandpack is an open-source project that lets you build playgrounds powered by the same bundler that CodeSandbox uses. The difference is that you have far more control over the look and feel of your playground.
Sandpack consists of two main packages:
sandpack-client: a small package that lets you hook into the Codesandbox bundler
sandpack-react: a set of React components that make it easy to interact with a Sandpack client
For this post, we're going to focus on the sandpack-react package because it abstracts away a lot of the manual steps involved when using the sandpack-client package directly.
How do you build a basic Sandpack playground?
The easiest way to build a Sandpack playground in React is to use the core Sandpack component:
Sweet!
Our playground has a basic editor and preview, but how does it get its content? All we're returning is <Sandpack template="react" />, but somehow, the playground is showing a "Hello World" application.
Sandpack comes with predefined templates.
You may have noticed we're passing a template prop to the Sandpack component. This is where the magic happens. Sandpack has a few templates baked into it for common frameworks like React and Vue.
In this case, because I set the template to react, we get this basic "Hello World" React app.
Note: Try changing the template above to "vue" and see what happens.
Ok!
So a "Hello World" app might seem cool, but it doesn't feel very useful. The built-in templates are a great starting point, but if you want to use Sandpack in your blog, you probably want your playground to show different code examples.
You can configure Sandpack's default files.
The good news is that Sandpack makes it easy to override the default template configuration. You can pass a set of files to the component that will be used to initialize the Sandpack instance:
The /App.js file in our files prop overwrites the built-in /App.js file.
One thing to keep in mind is that the key (i.e. file name) should be the relative file path you want to override or include. You can find the default files of a template in the Sandpack GitHub repo.
Note: Here's the list of files for the React template we're using.
Use the package.json file to add npm packages to your playground.
A code playground wouldn't be that useful if it didn't support using third-party packages. With Sandpack, you can do this with the package.json file. Override the default file and include whatever npm packages and versions you want.
Here's an example using a few Material UI packages to build an App Bar component:
Note: This was adapted from the Material UI App Bar documentation.
So what else can we do?
I promised you customization, right?
You can apply custom themes to your Sandpack instance.
If you're feeling adventurous, you can build a theme using the Sandpack theme builder. That said, Sandpack has several pre-defined themes in the sandpack-themes package. To use them, you just have to install the package and choose the theme you want.
Here's an example using the Gruvbox Dark theme:
Changing the theme is just the tip of the iceberg. There are way more things you can customize with Sandpack. All the examples we've looked at so far use the Sandpack component.
While this component is the easiest way to get started, Sandpack also gives us access to lower-level components to build even more unique experiences.
Create unique experiences using Sandpack's building blocks.
There are quite a few components that you can use, but here are a few core ones you'll probably reach for most often:
SandpackProvider(Essential): This component is required when using other low-level components. It uses React context to provide the other components with Sandpack's internal state.SandpackLayout: This component wraps other components like the Editor or Preview and gives the playground a basic responsive design.SandpackPreview: This component displays the bundled code in an iframe.SandpackCodeEditor: This component lets you update the code.
Let's see these components in action:
Each button in the example above changes how our playground looks. For example, the Flipped button swaps the order of the Editor and Preview components.
This is huge!
Sandpack's building blocks let you create any experience you can imagine.
How to build a custom Sandpack component.
If Sandpack's built-in components aren't enough, you can build your own components too! Sandpack has several hooks you can use to build these custom components.
Let's say you don't like Sandpack's default code editor. No problem! With a little bit of code, you can swap it out for something else.
Here's an example of how to use the popular Monaco editor:
Sandpack's useActiveCode hook returns the current code and a function to update the code. We pass both to the Monaco editor which uses them to update Sandpack's internal state which is reflected in the Preview.
We're also using the useSandpack hook to provide a key to the Monaco editor so that the editor state is reset when the file changes.
How am I using Sandpack in my blog?
This may be obvious, but all the Sandpack examples above require us to write React code. If you have control over your blog's code, installing and using Sandpack is straightforward. However, if your blog is hosted on a platform like Hashnode (like this blog), you won't be able to write code directly in a post.
So how am I able to get around this?
That's where Kempo comes into play.
I wanted a way to use Sandpack in my own blog, so I built an application that lets you configure Sandpack instances. All the examples above are Sandpack instances that are demoing Sandpack.
In other words, it's Sandpack instances all the way down!
I know what you're thinking.
Aren't we right back to using something like CodeSandbox to embed code playgrounds into our blogs?
I will admit that this is somewhat true, but there are some major differences. Kempo is built around configuring Sandpack. The goal is to use Sandpack's features without having to write code to configure and style Sandpack directly.
Just like Hashnode takes away the need to build a blogging platform so you can focus on your content, Kempo takes away the need to manually configure Sandpack so you can focus on your demos.
There are still improvements to be made, but for now, I think these are the main benefits:
Lightweight
Custom themes
Flexible components
Custom layouts for different screens
Note: You can learn more in my post where I introduce Kempo.
If you can use Sandpack directly in your blog then that's great, but if you're writing on a platform like Hashnode, Kempo might be a good fit.
If you do try using Kempo, let me know how it goes!
Either way, I hope this post gets you excited about Sandpack!