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.

Preview is controlled by the preview() function in your env's *.bit-env.ts file. It should look like this:

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

import { VueEnv } from '@bitdev/vue.vue-env';

import { Preview } from '@teambit/preview';
import { VuePreview } from '@bitdev/vue.dev-services.preview.vue-preview';
import webpackTransformer from './config/webpack.config';

export class MyVueEnv extends VueEnv {
  preview(): EnvHandler<Preview> {
    return VuePreview.from({
      mounter: require.resolve('./preview/mounter')
    });
  }
}

export default new MyVueEnv();
Copied

The Vue env renders your component previews in the local Bit dev server (bit start). You can use this to wrap your components with theme providers, route providers or any custom code you need.

Open your env's preview/mounter.tsx file to view the bare-bones configuration:

import { App } from 'vue';
import { createMounter } from '@bitdev/vue.dev-services.preview.vue-mounter';

/**
 * Customize a wrapper component for your component compositions (preview).
 */
import Wrapper from '@bitdev/vue.examples.my-vue-wrapper';

/**
 * Initialize your component compositions (preview) via Vue Application APIs
 * before it's mounted. For example, using a router, providing values, etc.
 * @see https://vuejs.org/api/application.html
 */
const initApp = (app: App<Element>) => {
  app.provide('message', 'hello')
};

/**
 * The entry for the app (preview runtime) that renders your component previews.
 * Use the default template or create your own.
 */
export default createMounter({
  initApp,
  Wrapper
});
Copied

There may be some cases where you need to apply custom bundler configurations for your component previews to render as expected. The default preview() function accepts bundler transformers. For example, to customize a Preview's webpack config, create and use a webpack transformer:

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

export class MyVueEnv extends VueEnv {
  preview(): EnvHandler<Preview> {
    return VuePreview.from({
      transformers: [webpackTransformer],
    });
  }
}

export default new MyVueEnv();
Copied

In some cases you will need to add components used in a custom preview mounter to the hostDependencies array.

export class MyEnv extends ${props.envnamepascal}Env {
  preview(): EnvHandler {
    return VuePreview.from({
      mounter: require.resolve('./preview/mounter'),
      hostDependencies: [
        /* your composition dependency */
        /* make sure to include the following dependencies, as well, they're needed for vue rendering */
        'vue',
        /* make sure to include the following dependencies, as well, they're needed for mdx rendering in bit's dev server */
        '@teambit/mdx.ui.mdx-scope-context',
        '@mdx-js/react',
        'react',
        'react-dom',
      ],
    });
  }
}
Copied

You can also customize the look and feel of the component documentation page (Overview page).

To do this, create a docs.tsx file in your env, add your customizations (e.g. providers) and consume it in the preview() function:

// ...
export class MyVueEnv extends VueEnv {
  // ...
  preview(): EnvHandler<Preview> {
    return VuePreview.from({
      // ...
      docsTemplate: require.resolve('./preview/docs'),
      // ...
    });
  }
  // ...
}
Copied

The docs.tsx file should look like this:

import { App } from 'vue';
import { createDocsTemplate } from '@bitdev/vue.dev-services.preview.vue-docs-template';

/**
 * Customize a wrapper component for your component compositions (preview) in docs.
 */
import Wrapper from '@bitdev/vue.examples.my-vue-wrapper';

/**
 * Initialize your component compositions (preview) in docs via Vue Application APIs
 * before it's mounted. For example, using a router, providing values, etc.
 * @see https://vuejs.org/api/application.html
 */
const initApp = (app: App<Element>) => {
  app.provide('message', 'hello')
};

/**
 * Customize the bit documentation template or
 * replace this with one of your own.
 * @see https://bit.dev/docs/vue-env/component-docs#docs-template
 */
export default createDocsTemplate({
  initApp,
  Wrapper
});
Copied