Histoire

1.0.0-beta.1 verified Mon Apr 27 auth: no javascript

Histoire is a fast, Vite-powered interactive storybook for Vue components, currently in v1.0.0-beta.1. It offers a lightweight alternative to Storybook with first-class Vite integration and zero-config setup. Released under active development with frequent beta updates, it supports Vue 3, Nuxt 4, and includes features like style isolation, CommonJS support, and a plugin API. Unlike Storybook, Histoire leverages Vite's native dev server for instant HMR and faster builds. Ships TypeScript types.

Common errors

error Cannot find module 'histoire/client' ↓

cause Using version <1.0.0-alpha.1 where client exports were not separated.

fix

Update histoire to v1.0.0-beta.1 or later, or use import from 'histoire' directly (but client exports may be missing).

error defineStory is not a function ↓

cause Using CommonJS require on an ESM-only export.

fix

Switch to ES module syntax: import { defineStory } from 'histoire'. If project is CJS, consider using dynamic import().

error Failed to resolve import "histoire" from "src/...story.vue" ↓

cause histoire is not installed or Vite cannot locate it.

fix

Run 'npm install -D histoire' and ensure it's in package.json devDependencies.

Warnings

breaking Breaking changes between v0.x and v1.0.0-beta: Story file structure changed, new client exports. ↓

fix Update imports to use 'histoire/client' for Story/Variant components, adjust story definitions.

gotcha CommonJS support is limited; some exports like defineStory are ESM-only. ↓

fix Use ESM imports (import { defineStory } from 'histoire') instead of require().

gotcha Vite peer dependency must be installed separately; histoire does not bundle Vite. ↓

fix Run 'npm install vite --save-dev' if not already present.

deprecated Old story API from v0.x (e.g., defineSetupStory) is deprecated. ↓

fix Migrate to setupStory and defineStory.

Install

npm install histoire

yarn add histoire

pnpm add histoire

Imports

defineStory
wrong
```
const { defineStory } = require('histoire')
```
correct
```
import { defineStory } from 'histoire'
```
ESM-only; CJS not available for this symbol. defineStory is the main export for defining stories.
setupStory
wrong
```
import { defineSetupStory } from 'histoire'
```
correct
```
import { setupStory } from 'histoire'
```
setupStory is used for shared story setup. Define functions are named differently.
Story
wrong
```
import { Story } from 'histoire'
```
correct
```
import { Story } from 'histoire/client'
```
Story component is exported from 'histoire/client' for use in story files.
Variant
```
import { Variant } from 'histoire/client'
```
Variant component for defining story variants, also from 'histoire/client'.

Quickstart

Quickstart showing installation, a basic story file with Story and Variant components, and dev server command.

// Install
npm install -D histoire

// Create a story file: stories/HelloWorld.story.vue
<template>
  <Story title="Hello World">
    <Variant title="Default">
      <div>Hello, World!</div>
    </Variant>
  </Story>
</template>

// Run dev server
npx histoire dev