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();
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:
The output is similar to the following:
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();
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.*" ] } }
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'), }); } }
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', ], }); } }
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:
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'), }); } }
For example, see this mounter component which replaces the root.render
with the older ReactDOM.render
to mount React 17 components.