Component Previews

A component's preview includes its documentation and compositions. Change the preview's configuration to customize how your docs and compositions are bundled and rendered.

To customize your components' preview, implement the preview method in your env.

/* @filename: my-react-env.bit-env.ts */

import { ReactEnv } from '@teambit/react.react-env';

import { Preview } from '@teambit/preview';
import { ReactPreview } from '@teambit/preview.react-preview';
import webpackTransformer from './config/webpack.config';

export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      /* preview config goes here */
    });
  }
}

export default new MyReactEnv();
Copied

A component's preview configuration does not affect production code.

Review your preview's webpack config by running the following on a component that uses your env:

$bit envs get pages/welcome

Copied

The output is similar to the following:

To modify your preview's Webpack config, implement the preview method in your custom env. Provide the transformers property with an array of Webpack config transformers.

For example:

// @filename: my-react-env.bit-env.ts
// ...
import webpackTransformer from './config/webpack.config';

export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      transformers: [webpackTransformer],
    });
  }
}

export default new MyReactEnv();
Copied

Learn how to create a Webpack transformer in Webpack transformers.

Compositions are a component's rendering in different contexts and variations. Compositions are displayed the component's 'Compositions' tab.

Update the glob patterns listed in your env's env.jsonc file to determine which files, in a component's directory, should be loaded as compositions.

{
  "patterns": {
    "compositions": [
      "**/*.composition.*",
      "**/*.preview.*",
      "**/*.my-custom-pattern.*"
    ]
  }
}
Copied

Since compositions are only used for development, every composition file is considered as a dev file.

A single component can have multiple composition files.

Your components might require a certain context for them to function properly, or to better simulate their behavior in possible host applications.

Set your composition provider with the right "wrapper" components, to avoid repeating that task in every composition, and to standardize your compositions' "playground".

The following example wraps every composition with a theme provider:

// ...
export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      mounter: require.resolve('./preview/mounter'),
    });
  }
}
Copied

Composition providers, like other peer dependencies used for component previewing, should be included only once in your env's bundle and excluded from your components' preview bundle. This is done using the hostDependencies property. For example:

export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      mounter: require.resolve('./preview/mounter'),
      hostDependencies: [
        /* your composition provider */
        '@learnbit-react/material-ui.theme.theme-provider',
        /* make sure to include the following dependencies, as well */
        '@teambit/mdx.ui.mdx-scope-context',
        '@mdx-js/react',
        'react',
        'react-dom',
      ],
    });
  }
}
Copied

The mounter component is responsible for mounting your compositions to the page. Replace the default mounter with your own component, to modify the way components are being mounted.

Run the following to fork the default mounter:

$bit fork teambit.react/mounter my-custom-mounter

Copied

Modify the forked component (mounter) and use it to replace the default mounter:

// ...
export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      mounter: require.resolve('./preview/mounter'),
    });
  }
}
Copied

For example, see this mounter component which replaces the root.render with the older ReactDOM.render to mount React 17 components.