
## Will Preview.js work with my project?

If you use Preact 10+, React 16.14+, 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.

Preview.js Pro also lets you save your previews as Storybook stories.

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.



:::caution Experimental

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

:::

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

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.

If you try to preview a component that depends on a particular React context or some other global state, it will
crash unless you set up a [`<Wrapper />` component](/docs/config/wrapper) to mock the required parts of your app and set up context providers.

Here are some common examples. You may need to combine them if you use several of these libraries (e.g. React Router + Redux).

## Usage with React Router v5

```tsx
// __previewjs__/Wrapper.tsx

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

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

## Usage with React Router v6

```tsx
// __previewjs__/Wrapper.tsx

import React from "react";
import { RouterProvider, createBrowserRouter } from "react-router-dom";
import "../src/index.css";

export const Wrapper = ({ children }) => (
  <RouterProvider router={createBrowserRouter([{path: '*', element: children}])} />
);
```

## Using Redux

```tsx
// __previewjs__/Wrapper.tsx

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

export const Wrapper = ({ children }) => (
  <Provider store={store}>
    {children}
  </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.tsx` file](/docs/config/wrapper) that imports the `@previewjs/config-helper-nextjs` package (which you will need to install):

```tsx
// __previewjs__/Wrapper.tsx

import "../styles/global.css";
import "@previewjs/config-helper-nextjs";
```

## 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](/docs/config/wrapper) 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 [`Wrapper` component](/docs/config/wrapper):

```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. SvelteKit components are not expected to work.

:::

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 [`Wrapper` component](/docs/config/wrapper):

```html

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

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

Svelte


Preview.js automatically loads your PostCSS config, so Tailwind should just work.

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


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.

<DocImage
  src="/docs/vscode-extension.png"
  href="https://marketplace.visualstudio.com/items?itemName=zenclabs.previewjs"
/>


Visual Studio Code


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.

<DocImage
  src="/docs/jetbrains-plugin.png"
  href="https://plugins.jetbrains.com/plugin/18384-preview-js"
/>


IntelliJ / WebStorm


```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!

<DocImage src="/docs/cli.png" />


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.

## Global CSS

Preview.js looks for [global CSS files](https://github.com/fwouts/previewjs/blob/4b09d926e6be3118adb041575f07d6c00b60388e/core/src/previewer.ts#L30) such as `style.css` or `global.scss`, but this is a best-effort strategy.

In order to explicitly import global CSS, you can set up a [wrapper file](/docs/config/wrapper):

<Tabs>
<Tab name="React | Preact | Solid">

```tsx
// __previewjs__/Wrapper.tsx

import "../src/index.css";
```

</Tab>
<Tab name="Svelte">

```html
// __previewjs__/Wrapper.svelte

<script lang="ts">
  import "../src/index.css";
</script>
<div>
  <slot />
</div>
```

</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, defined in the `__previewjs__` directory at the root of your project (next to your `package.json`). You can also use this file to set up any global variables.

<Tabs>
<Tab name="React | Preact">

```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="Solid">

```tsx
import { ParentComponent } from "solid-js";

export const Wrapper: ParentComponent = ({ children }) => {
  return <div class="wrapped">{children}</div>;
};
```

</Tab>
<Tab name="Svelte">

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

</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 | Preact | Solid">

```js
// preview.config.js

import { defineConfig } from "@previewjs/config";

export default defineConfig({
  wrapper: {
    path: "src/PreviewWrapper.jsx",
    componentName: "default",
  },
});
```

</Tab>
<Tab name="Svelte">

```js
// preview.config.js

import { defineConfig } from "@previewjs/config";

export default defineConfig({
  wrapper: {
    path: "src/PreviewWrapper.svelte",
  },
});
```

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

```js
// preview.config.js

import { defineConfig } from "@previewjs/config";

export default defineConfig({
  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:

```js
import icon from "./icon.svg";
```

If you prefer to use explicit paths instead, you may need to configure a public directory in `preview.config.js`:

```js
// preview.config.js

import { defineConfig } from "@previewjs/config";

export default defineConfig({
  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 want `ui-components/Button` to map to
`src/ui/components/Button.tsx`, 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 rely 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

import { defineConfig } from "@previewjs/config";
import { svgr } from "vite-plugin-react-svgr";

export default defineConfig({
  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: { ... }
      }),
    ],
  },
});
```


Activating Preview.js Pro