seek-oss/playroom: a JSX design environment built on your own components

What problem seek-oss/playroom solves, and who it is for

A design system has two audiences with incompatible needs. Engineers want the component API, the props, the build. Designers want to see the thing rendered at 320, 768 and 1024 pixels wide, in every theme, without cloning a repository or waiting on a deploy. Playroom targets the second audience by giving them the first audience's medium: JSX against the real component library.

The README frames the goal as creating "a zero-install code-oriented design environment, built into a standalone bundle that can be deployed alongside your existing design system documentation." That last clause matters. Playroom is not the documentation site. It is a companion artifact you host next to one, and the README's demo list (Braid, Cubes, Mesh, Mística, Shopify Polaris, Agriculture Design System) shows the pattern: a design system ships docs, then ships a Playroom instance at a path like /playroom/.

It is for teams whose components are already React and already exported from a single entry point. If your design system is CSS-only, or distributed as design tokens with no React layer, there is nothing here to render.

How Playroom renders your library: config in, iframe out

The mechanism is a build step plus a sandboxed frame. Playroom reads playroom.config.js from your project root, resolves the paths you give it (components, themes, snippets, frameComponent, scope), and compiles them into a standalone bundle with its own webpack pipeline. The webpackConfig option lets you merge your own loader rules into that pipeline, which is the escape hatch for anything unusual in your component source.

The rendered output lives in an iframe whose sandbox attribute you control through iframeSandbox. The README is explicit that "A minimum of allow-scripts is required for Playroom to work," which tells you the frame executes your components rather than rendering them to static HTML. The frame also has a frameComponent hook, a wrapper you supply, and frameSettings, an array of toggles such as the documented rtl example with an id, a label and a defaultValue. Those settings are how you expose direction or density switches without forking the tool.

Themes and widths are first-class rather than a filter applied after the fact. themes points at a module, widths is a numeric array, and defaultVisibleWidths and defaultVisibleThemes take subsets of those to control what appears on first load. That combination is the actual product: the same JSX evaluated simultaneously across every combination you declared.

State lives in the URL. The README lists sharing as a feature ("Share your work with others by simply copying the URL"), and the paramType option decides whether that state is encoded in the query string or the fragment, with hash as the default. baseUrl exists for the case where the bundle is not served from the domain root.

Installing Playroom and running a first component

Install it as a dev dependency. The README uses npm; the repository itself is a pnpm workspace with pnpm-lock.yaml and pnpm-workspace.yaml at the root, so pnpm will also work, but the documented path is npm.

npm install --save-dev playroom

Add the two scripts the README gives. playroom start runs a local development server, playroom build emits the production bundle.

{
  "scripts": {
    "playroom:start": "playroom start",
    "playroom:build": "playroom build"
  }
}

Create playroom.config.js at the project root. Only components and outputPath are required; everything else has a default. The README notes that port and openBrowser default to 9000 and true when omitted, so the server comes up on port 9000 and opens a browser tab.

module.exports = {
  components: './src/components',
  outputPath: './dist/playroom',
  title: 'My Awesome Library',
  themes: './src/themes',
  widths: [320, 768, 1024],
  port: 9000,
  openBrowser: true
};

The components module must export a single object or a set of named exports. The README's example re-exports both styles, and mixing them in one file is fine.

export { default as Text } from '../Text';
export { Button } from '../Button';

Start the server with npm run playroom:start and you should see the editor with your components in scope and the widths you listed as columns. To produce the deployable artifact, run npm run playroom:build and point your static host at outputPath.

Where Playroom stops: no docs, no types, no rollback story

Playroom renders components. It does not describe them. There is no prop table, no usage prose, no generated API reference, and nothing in the README suggests one. Teams that adopt it expecting a Storybook replacement will find the discovery half missing: a new engineer opening Playroom sees an editor and a canvas, not a catalogue of what exists and what each prop does.

The editor is a code box, not an IDE. Nothing in the documented options mentions TypeScript-aware completion or type checking inside the editor, even though the project itself is written in TypeScript and ships types for its utility exports (the package.json types field points at ./dist/utils/index.d.cts). Your components' types do not become editor assistance here.

The iframeSandbox setting is a real footgun. Because the frame needs allow-scripts, teams sometimes widen the sandbox attribute to make an integration work, and the README gives no guidance on which additional tokens are safe. It documents the minimum and stops. If you are hosting Playroom on a shared domain with anything authenticated, that is a decision you make without help from the docs.

Finally, the README does not document rollback, version pinning strategy, or what happens when a Playroom upgrade changes the URL encoding. Since sharing depends on URLs, a change in paramType handling or in how state serialises would silently break links people have pasted into tickets. The changelog is the place to look, and the release history shows a steady cadence rather than a frozen format.

Playroom compared with Storybook

Storybook is the obvious alternative and the difference is philosophical. Storybook organises around stories: a developer writes named fixtures per component, and the tool generates navigation, docs pages and controls from them. The unit of work is the component, and the output is a catalogue.

Playroom inverts that. There are no per-component stories. You point it at a components module, and the unit of work becomes a free-form JSX document that you write in the browser, across the themes and widths you configured. The output is a canvas, and the sharing primitive is a URL rather than a story id.

That makes Playroom cheaper to wire up (two config keys and a components file, versus a per-component story convention) and worse at onboarding. It also makes Playroom better at a specific job Storybook handles awkwardly: checking whether a layout survives at 320 and 1024 in the dark theme at the same time, in the same viewport, with the same JSX.

The README's own framing supports running both. It describes the bundle as something "deployed alongside your existing design system documentation," not instead of it.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-22. Releases in the current line are v1.2.1 (2026-02-27), v1.2.2 (2026-03-30) and v1.3.0 (2026-07-01), so the project is being cut at a regular cadence rather than sitting still. It is maintained by SEEK's open source group, and the published package ships only CHANGELOG.md and dist, which means installing it does not pull the source tree into your node_modules.

Upgrade cost is the interesting part. Playroom generates a bundle with its own webpack pipeline and merges your webpackConfig on top. A major webpack or Babel change upstream can collide with your overrides, so the config file is the surface to watch when you bump versions. The .changeset directory in the repository indicates changesets are used to track releases, so the CHANGELOG is the authoritative record of what moved.

Licence is MIT, which permits commercial use and modification. That is a statement about the licence text, not advice about your situation; if you redistribute a modified Playroom, read the LICENSE file at the repository root and handle attribution accordingly.

Editorial conclusion

Adopt Playroom if you already ship a React component library and want a zero-install surface where designers and engineers write real JSX across themes and widths, and where a shared URL reproduces the exact state. Do not adopt it if you need an API reference, written guidance, or a code editor with language-server features; it renders components, it does not document them. Before committing, verify two things in your own checkout: that your components entry point resolves through the webpack config Playroom generates, and that your iframeSandbox value is at least allow-scripts, otherwise the preview frame stays blank.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. seek-oss/playroom on GitHub