Playroom

Define predefined snippets of JSX that users can quickly insert into the Playroom editor. Create a file (e.g., snippets.js) and export an array of objects.

Each object can contain:

• group (optional): A string to group snippets in the UI.
• name (required): The name of the snippet.
• description (optional): A description to help differentiate snippets.
• code (required): The JSX code string.

export default [
  {
    group: 'Components',
    name: 'Button',
    description: 'Strong weight',
    code: `
      <Button weight="strong">
        Button
      </Button>
    `,
  },
];

Install Playroom as a development dependency and add the necessary scripts to your package.json to start the development server or build assets for production.

1. Install the package:

$ npm install --save-dev playroom

2. Add these scripts to your package.json:

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

3. Create a playroom.config.js file in your project root to configure your environment.

Define boolean toggles that users can control for each frame independently (e.g., for testing RTL or touch targets). Configure these in playroom.config.js using the frameSettings array.

Each setting object requires:

• id: A unique identifier.
• label: The display name in the UI.
• defaultValue: The initial boolean state.

module.exports = {
  // ...
  frameSettings: [
    {
      id: 'rtl',
      label: 'RTL Layout',
      defaultValue: false,
    },
    {
      id: 'showTouchTargets',
      label: 'Show Touch Targets',
      defaultValue: false,
    },
  ],
};

Playroom uses react-docgen-typescript to parse static prop types for better autocompletion in the editor. By default, it includes all .ts and .tsx files in the current working directory (excluding node_modules).

To customize which files are included, use the typeScriptFiles property in your playroom.config.js. This property accepts an array of tinyglobby-compatible globs.

module.exports = {
  // ...
  typeScriptFiles: ['src/components/**/*.{ts,tsx}', '!**/node_modules'],
};

You can customize the parser options used for TypeScript prop parsing by setting the reactDocgenTypescriptConfig property in your playroom.config.js. This allows you to pass configuration directly to react-docgen-typescript, such as a propFilter function.

module.exports = {
  // ...
  reactDocgenTypescriptConfig: {
    propFilter: (prop, component) => {
      // ...
    },
  },
};

Playroom requires a configuration file to run. The CLI automatically searches for the following files in your current working directory (or parent directories) in this order:

1. playroom.config.js
2. playroom.config.mjs
3. playroom.config.cjs

If you do not have one of these files in your project root, you must specify the path manually using the --config flag.

Access the current state of frame settings via the frameSettings prop in your custom FrameComponent. This allows you to pass settings (like rtl) down to your component library's providers or apply CSS classes based on the toggle state.

import React from 'react';
import { ThemeProvider } from '../path/to/your/theming-system';

export default function FrameComponent({ theme, frameSettings, children }) {
  return (
    <ThemeProvider theme={theme} rtl={frameSettings?.rtl}>
      <div
        className={
          frameSettings?.showTouchTargets ? 'showTouchTargets' : undefined
        }
      >
        {children}
      </div>
    </ThemeProvider>
  );
}

If your components require specific providers (like a ThemeProvider), use the frameComponent option in your config to provide a custom wrapper. The component must export a default React component that receives the following props:

• theme: The currently selected theme object.
• themeName: The name of the currently selected theme.
• frameSettings: An object mapping setting IDs to their boolean values.
• children: The rendered Playroom code.

import React from 'react';
import { ThemeProvider } from '../path/to/your/theming-system';

export default function FrameComponent({ theme, children }) {
  return <ThemeProvider theme={theme}>{children}</ThemeProvider>;
}

Use the scope option to provide extra variables to the JSX environment. The specified file must export a useScope hook that returns a scope object containing the variables you want to expose.

// scope.js

import { useTheme } from '../path/to/your/theming-system';

export default function useScope() {
  return {
    theme: useTheme(),
  };
}