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();
CopiedCopy

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

Webpack configuration

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

$bit
Copiedcopy

The output is similar to the following:

Environment: my-org.my-scope/examples/my-react-env

teambit.compilation/bundler

dev server config:

{ mode: 'development', devtool: 'inline-source-map', ... } ...

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();
CopiedCopy

Learn how to create a Webpack transformer in Webpack transformers.

Compositions

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

Composition files glob pattern

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.*"
    ]
  }
}
CopiedCopy

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

A single component can have multiple composition files.

Composition providers

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:

my-react-env.bit-env.ts
preview/mounter.tsx
// ...
export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      mounter: require.resolve('./preview/mounter'),
    });
  }
}
CopiedCopy

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',
      ],
    });
  }
}
CopiedCopy

Composition mounter

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
Copiedcopy

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

my-react-env.bit-env.ts
preview/docs.tsx
// ...
export class MyReactEnv extends ReactEnv {
  preview(): EnvHandler<Preview> {
    return ReactPreview.from({
      mounter: require.resolve('./preview/mounter'),
    });
  }
}
CopiedCopy

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