
## Will Preview.js work with my project?

If you use Preact 10+, React 16+, Solid, Svelte 3 or Vue 2/3, you should be fine.

## How is Preview.js different from Storybook?

[Storybook](https://storybook.js.org) is an amazing tool to document UI components. We highly recommend writing component stories with Storybook, especially if you work in a team of engineers. Kudos to the Storybook team for building such a great piece of software ❤️

Preview.js serves a different use case. It's best used to quickly visualise a component without having to write any boilerplate code. It's also much faster, at least until Storybook migrates off Webpack ([which might happen soon!](https://storybook.js.org/blog/storybook-for-vite/)).

In summary, Preview.js and Storybook can work hand-in-hand.

## Will my CSS work?

Preview.js can handle CSS-in-JS libraries such as Styled Components and Emotion. It also supports CSS imports, including CSS Modules. You can also use SASS or LESS.

If your specific use case doesn't work, please [file an issue](https://github.com/fwouts/previewjs/issues/new).

## How does Preview.js work?

There are a few pieces to the puzzle, and you can [check out the source yourself](https://github.com/fwouts/previewjs).

In summary:

- [TypeScript's Compiler API](https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API) enables us to detect components.
- [Vite](https://vitejs.dev) and [esbuild](https://esbuild.github.io) enable incredibly fast refresh.
- Source code is served from a virtual filesystem that updates on every keystroke.
- A fair bit of code ties it all together nicely.



Preview.js can detect all components in your project, and let you quickly browse through them.

## See it in action

<DocVideo src="/videos/search-react.mp4" />

:::tip
Hit **Cmd/Ctrl+K** to open component search instantly within Preview.js Pro.
:::


Component search

Getting started


React projects created using [Create React App](https://create-react-app.dev) or [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) should work out of the box with Preview.js, even if you use CSS-in-JS libraries
such as Styled Components or Emotion.

You can confirm this by testing Preview.js with a simple `<HelloWorld />` component:

<DocImage src="/docs/react-example.png" />

Assuming this works fine, it's time to try Preview.js with other components. It's important to understand that
not every component will preview successfully, because Preview.js renders them in isolation. This means that
if you try to preview a component that depends on a particular React context or some other global state, it will
likely crash.

This can typically be remediated by mocking the required parts of your app and setting up React context providers
in a "wrapper" component. You do this by creating a file named `__previewjs__/Wrapper.tsx` that exports a `<Wrapper />`
component.

Here is an example to ensure React Router and Redux play nice with Preview.js:

```tsx
// __previewjs__/Wrapper.tsx

import React from "react";
import { Provider } from "react-redux";
import { BrowserRouter } from "react-router-dom";
import store from "../src/redux";
import "../src/index.css";

export const Wrapper = ({ children }) => (
  <Provider store={store}>
    <BrowserRouter>{children}</BrowserRouter>
  </Provider>
);
```


React & Preact


While [Next.js](https://nextjs.org) is based on React, it requires a little extra setup to work perfectly with Preview.js.

In particular, since Preview.js renders components in isolation (and therefore outside of Next.js), they may crash
when you use `<Link />` or `<Image />`, or when you try to access the router with `useRouter()`.

This can be remediated by configuring a `<Wrapper />` component:
```tsx
// __previewjs__/Wrapper.tsx

import "../styles/global.css";
import "@previewjs/config-helper-nextjs";  // You will need to install this package.
```

## Custom implementation

If you'd like more precise control over how Next.js is mocked, you can start with the following code:

```tsx
// __previewjs__/Wrapper.tsx

import "../styles/global.css";

import * as NextImage from "next/image";
import * as NextRouter from "next/router";

const OriginalNextImage = NextImage.default;

// Patch Image to disable optimisations within Preview.js.
Object.defineProperty(NextImage, "default", {
  configurable: true,
  value: (props: NextImage.ImageProps) => (
    <OriginalNextImage {...props} unoptimized />
  ),
});

// Patch useRouter() to fake the router within Preview.js.
Object.defineProperty(NextRouter, "useRouter", {
  configurable: true,
  value: () => ({
    locale: "en-US",
    route: "/",
    pathname: "/",
    query: {},
    asPath: "/",
    push() {
      return Promise.resolve(true);
    },
    replace() {
      return Promise.resolve(true);
    },
    reload() {},
    back() {},
    prefetch() {
      return Promise.resolve();
    },
    beforePopState() {},
    events: {
      on() {},
      off() {},
      emit() {},
    },
    isFallback: false,
  }),
});
```


Next.js

Both Vue 2 and Vue 3 are supported out of the box by Preview.js.

Since components are rendered in isolation, you may need to set up a custom `Wrapper`
component to set up the required context or Vue plugins.

<Tabs>
<Tab name="Vue 3">

```html


<script setup>
  import "../src/styles.css";
  import { getCurrentInstance } from "vue";

  const { appContext } = getCurrentInstance();
  appContext.app.use(mockRouter);
</script>
<template>
  <div class="wrapper">
    <slot />
  </div>
</template>
```

</Tab>

<Tab name="Vue 2">

```html


<script>
  import "../src/styles.css";

  import Vue from "vue";
  import BootstrapVue from "bootstrap-vue";
  import i18n from "@/i18n";

  Vue.use(BootstrapVue);

  export default Vue.extend({
    i18n,
  });
</script>
<template>
  <div class="wrapper">
    <slot />
  </div>
</template>
```

</Tab>
</Tabs>

Vue.js


Preview.js supports both Nuxt 2 and Nuxt 3. See [instructions for Vue](/docs/examples/vuejs) for general Vue configuration.

If you use Nuxt 3 with auto-imports, you may find that Preview.js isn't able to handle them correctly.

You can remediate this by installing `unimport` in your project and setting up a [Vite](https://vitejs.dev) configuration:

```
// vite.config.ts

import Unimport from "unimport/unplugin";

export default {
  plugins: [
    Unimport.vite({
      include: [/\.[tj]sx?$/, /\.vue$/, /\.vue\?vue/],
      presets: ["vue"],
      addons: {
        vueTemplate: true,
      },
    }),
  ],
};
```

You can test this configuration with the following component:

```html
<script setup>
  /* ref() and computed() are auto-imported */
  const count = ref(1);
  const double = computed(() => count.value * 2);
</script>
<template>
  <div>{{ double }}</div>
</template>
```

Note that Nuxt-specific components such as `NuxtWelcome` cannot be auto-imported by Preview.js.


Nuxt.js


Solid projects should work out of the box with Preview.js.

If you need to set up global state or wrap your components, you can create a file named `__previewjs__/Wrapper.tsx` that exports a `<Wrapper />` component:

```tsx
// __previewjs__/Wrapper.tsx

import "../src/styles.css";

export const Wrapper = ({ children }: { children: JSX.Element }) => {
  return <div className="wrapped">{children}</div>;
};
```


Solid

:::caution Experimental

Svelte support is experimental as of v1.16. Please report bugs!

:::

Svelte projects should work out of the box with Preview.js.

If you need to set up global state or wrap your components, you can create a file named `__previewjs__/Wrapper.svelte`:

```html

<script>
  import "../src/styles.css";
</script>

<div class="wrapped">
  <slot />
</div>
```

Svelte


Preview.js automatically loads your PostCSS config, so Tailwind will generally work out of the box.

If Tailwind isn't detected automatically, make sure that you have a `postcss.config.js` file (or equivalent), such as:

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

If Tailwind still isn't detected by Preview.js, you may need to [set up a wrapper that imports your global CSS](/docs/config/css).


Tailwind

Setup guides


<DocVideo src="/videos/platform-vscode.mp4" />

## Installing

Install Preview.js from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=zenclabs.previewjs) or by searching for "Preview.js" in the **Extensions** panel of Visual Studio Code.


Visual Studio Code


<DocVideo src="/videos/platform-intellij.mp4" />

## Installing

Install Preview.js from the [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/18384-preview-js) or by searching for "Preview.js" in the **Plugins** window of IntelliJ / WebStorm.


IntelliJ / WebStorm


<DocVideo src="/videos/platform-cli.mp4" />

## Installing

Install Preview.js CLI:

```sh
# pnpm
$ pnpm add -D @previewjs/cli

# npm
$ npm install --dev @previewjs/cli

# Yarn
$ yarn add -D @previewjs/cli
```

You can then run `previewjs` in your project directory and pick any component to preview!


Command-line interface

Platforms


Thanks to a strong foundation provided by [Vite](https://vitejs.dev), most CSS-in-JS libraries will work out of the box, as well as plain CSS imports and CSS modules.

However, you may need some minimal set-up for global CSS to work.

## Global CSS

Since Preview.js renders components in isolation, it doesn't run any top-level entry points that you may have set up in your app.

In order to import global CSS, you can set up a wrapper component:

<Tabs>
<Tab name="React">

```tsx
// __previewjs__/Wrapper.tsx

import "../src/index.css";
import React from "react";

export const Wrapper = React.Fragment;
```

</Tab>
<Tab name="Vue 2">

```html
// __previewjs__/Wrapper.vue

<template>
  <slot />
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
<Tab name="Vue 3">

```html
// __previewjs__/Wrapper.vue

<template>
  <slot />
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
</Tabs>

## PostCSS / Tailwind

If your CSS relies on PostCSS, it will be picked up as long as your project has a `postcss.config.js` file.

For example for Tailwind, here is the required configuration:

```js title="/postcss.config.js"
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};
```

You should also make sure that you import the global CSS as explained above.



By default, each component is rendered in a blank page.

If you rely on your components being rendered in a specific hierarchy such as a padded box or specific React providers, you may want to wrap components instead. 

This is done by creating a Wrapper component. You can also use this file to set up any global variables.

<Tabs>
<Tab name="React">

```tsx
// __previewjs__/Wrapper.tsx

import React from 'react';
import "../src/index.css";

export const Wrapper: React.FC = ({ children }) => (
  <>
    <MyContext.Provider value={...}>
      <div className="wrapped">
        {children}
      </div>
    </MyContext.Provider>
  </>
);
```

</Tab>
<Tab name="Vue 2">

```html
// __previewjs__/Wrapper.vue

<template>
  <div class="wrapped">
    <slot />
  </div>
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
<Tab name="Vue 3">

```html
// __previewjs__/Wrapper.vue

<template>
  <div class="wrapped">
    <slot />
  </div>
</template>
<style>
  @import "../src/index.css";
</style>
```

</Tab>
</Tabs>

You can customise the wrapper's location in `preview.config.js`:

<Tabs>
<Tab name="React">

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  wrapper: {
    path: "src/PreviewWrapper.jsx",
    componentName: "default",
  },
};
```

</Tab>
<Tab name="Vue">

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  wrapper: {
    path: "src/PreviewWrapper.vue",
  },
};
```

</Tab>
</Tabs>
```


Wrapping components


Your components may depend on static assets such as images.

Preview.js automatically lets you import any asset with an `import` statement.

If you prefer to use explicit paths instead, you may need to configure a public directory.

This is done via the `publicDir` property in `preview.config.js`:

```js
// preview.config.js

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  publicDir: "static",
};
```


Static Assets


If you use custom aliases, you may need to help Preview.js resolve imports.

Since Preview.js uses [Vite](https://vitejs.dev/) under the hood, you just need to configure Vite with [`resolve.alias`](https://vitejs.dev/config/shared-options.html#resolve-alias).

For example if you use statements such as `import ... from "ui-components/Button"` that should map to
`src/ui/components/Button`, you will need the following configuration:

```js
// vite.config.js

export default {
  resolve: {
    alias: {
      "ui-components": "src/ui/components",
    },
  },
};
```

## js/tsconfig.json support

Preview.js can automatically detect aliases from `tsconfig.json` (as well as `jsconfig.json`). As a result, you may not need to explicitly provide aliases.


Custom Aliases


Your code may be relying on SVG files imported as React components, such as:

```js
import { ReactComponent as Logo } from "./logo.svg";
```

In order to make this work, you will need to add a dev dependency on `vite-plugin-react-svgr` (or any other SVGR plugin for Vite) and customise `preview.config.js`:

```js
// preview.config.js
const { svgr } = require("vite-plugin-react-svgr");

/** @type {import("@previewjs/config").PreviewConfig} */
module.exports = {
  vite: {
    plugins: [
      svgr({
        exportAs: "ReactComponent",
        // exportAs: "default" if you want `import Logo from "./logo.svg"` instead

        // If you import SVG files via an alias, you'll need to also pass "alias" here.
        // See https://previewjs.com/docs/config/aliases
        //
        // alias: { ... }
      }),
    ],
  },
};
```


SVGR support (React only)


:::caution Experimental

React Native is not officially supported at this stage. Preview.js will only work for a subset of components.

**Requirement:** Preview.js v1.8.0 (VS Code / IntelliJ) or `@previewjs/cli` v1.2.0

:::

You can preview React Native components, as long as they don't depend on `expo` packages. For example, if your component depends directly or indirectly on `expo-web-browser`, it will fail to preview.

**This means that your root App component is unlikely to work with Preview.js.**

## Testing your components with dark theme

In order to force your components to be rendered with the dark color theme, insert the following code in your [Wrapper](/docs/config/wrapper) file.

```tsx
// __previewjs__/Wrapper.tsx

import { Appearance } from "react-native";

Appearance.getColorScheme = () => "dark";
```

:::info Request for contributions

If you're familiar with [Vite](https://vitejs.dev) and find out how to make your React Native Web app with Expo compile, feel free to [open an issue](https://github.com/fwouts/previewjs/issues) sharing your sample repo!

See https://github.com/vitejs/vite/issues/3195 for more context on the issue.

:::


React Native

Configuration


Preview.js lets you specify what properties to pass to your component.

Whenever possible, suitable props will be automatically generated based on detected types.

For example, say that you have the following component in React:

```tsx
export const Button = (props: { label: string; disabled: boolean }) => {
  return <button disabled={props.disabled}>{props.label}</button>;
};
```

The following props will automatically be generated by Preview.js:

```js
properties = {
  label: "label",
  disabled: false,
};
```

This also works for Vue components, including the newer [`<script setup>`](https://vuejs.org/api/sfc-script-setup.html) syntax used in Vue 3.

## See it in action

<Tabs>
  <Tab name="React">
    <DocVideo src="/videos/autogenerated-props-react.mp4" />
  </Tab>
  <Tab name="Vue">
    <DocVideo src="/videos/autogenerated-props-vue.mp4" />
  </Tab>
</Tabs>


Autogenerated props


Preview.js updates your component's preview on every keystroke so you can focus on your code.

No need to press Cmd/Ctrl+S all the time!

## See it in action

<Tabs>
  <Tab name="React">
    <DocVideo src="/videos/instant-refresh-react.mp4" />
  </Tab>
  <Tab name="Vue">
    <DocVideo src="/videos/instant-refresh-vue.mp4" />
  </Tab>
</Tabs>


Instant refresh


Preview.js supports the [Component Story Format (v2 and v3)](https://storybook.js.org/docs/react/api/csf), in particular `args` and `decorators`.

You can work on stories within Preview.js. No need to wait for Storybook to spin up anymore!

<DocVideo src="/videos/storybook-react.mp4" />

:::caution

Preview.js does not support the legacy `storiesOf()` API.

Storybook addons are ignored when running inside Preview.js.

If you run into any issues, feel free to [open a GitHub issue](https://github.com/fwouts/previewjs/issues).

:::


Storybook


Developing a responsive component? You can pick from a series of preconfigured viewports, or choose your own.

In addition, you can zoom in/out to tweak your component until it's truly pixel-perfect.

## See it in action

<DocVideo src="/videos/viewports-vue.mp4" />


Viewport preview


By default, Preview.js uses a white background. Sometimes, that's not what you want.

You can either set a background color in [your wrapper component](/docs/config/wrapper) or use the dark background toggle available in [Preview.js Pro](/#pro).

## See it in action

<DocVideo src="/videos/dark-background-toggle-vue.mp4" />


Dark background toggle


The component picker allows you to switch instantly between components defined in the same file, as well as corresponding Storybook stories.

For example, when `HeroHeader.tsx` defines two components `HeroHeader` and `Title`, and another file `HeroHeader.stories.tsx` defines various Storybook stories for these buttons, you'll be able to switch between all of them without leaving Preview.js.

## See it in action

<DocVideo src="/videos/switcher-react.mp4" />


Activating Preview.js Pro