Histoire Documentation

Histoire is a Vite-native tool used to generate "stories applications" (or "books") to showcase, document, and test components in isolation. It is particularly useful for building design systems or component libraries.

Core Concepts

• Story: A scenario showcasing one or more components for specific use cases.
• Variant: Different use cases within a single Story, often representing different states or configurations of the same component.
• Book: The collection of stories generated by Histoire.

Key Benefits

• Vite-native: Reuses your existing Vite configuration, providing out-of-the-box support for TypeScript, JSX, and Styles.
• Idiomatic: Allows you to write stories naturally using .vue, .svelte, or JSX without mandatory proprietary syntax.
• Fast: Leverages Vite's instant server startup and HMR (Hot Module Replacement).

Histoire provides builtin controls and components that can be used within your stories. The implementation and usage details depend on your framework:

• For Vue: Refer to the Vue 3 builtin controls guide.
• For Svelte: Refer to the Svelte 3 builtin controls guide.

By default, Histoire uses the title prop of your <Story> component to build the explorer tree hierarchy. To place a story in a specific folder or subfolder, provide a path-like string to the title prop.

<template>
  <Story title="Folder/Sub Folder/My story" >
    <!-- Your story goes here -->
  </Story>
</template>

To enable global component types in your project, create an env.d.ts file in your project root and add the @histoire/plugin-vue/components reference. Ensure this file is included in your tsconfig.json's include array.

/// <reference types="@histoire/plugin-vue/components" />

{
  "compilerOptions": {
    "target": "es2017",
    "module": "esnext",
    "lib": ["esnext"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "strictNullChecks": true,
    "resolveJsonModule": true,
    "jsx": "preserve"
  },
  "include": [
    "env.d.ts",
    "src/**/*",
    "src/**/*.vue"
  ]
}

For a consistent UI, use Histoire's built-in control components inside the #controls slot. These components support v-model and an optional title prop. Common examples include <HstText /> and <HstCheckbox />.

<template>
  <Story>
    <Variant>
      <MyButton :disabled="state.disabled">
        {{ state.content }}
      </MyButton>

      <template #controls>
        <HstText v-model="state.content" title="Content" />
        <HstCheckbox v-model="state.disabled" title="Disabled" />
      </template>
    </Variant>
  </Story>
</template>

You can write markdown documentation directly inside your Vue story files by using the <docs> tag with the lang="md" attribute. This allows you to keep documentation and component logic in the same file.

<template>
  <!-- Your story goes here -->
</template>

<docs lang="md">
# My documentation

Checkout this [cool video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)!
</docs>

To use Histoire with a Vue 3 project, install the histoire core package and the @histoire/plugin-vue plugin as development dependencies. After installation, create a histoire.config.js or histoire.config.ts file in your project root and register the HstVue plugin using defineConfig.

pnpm i -D histoire @histoire/plugin-vue
# OR
npm i -D histoire @histoire/plugin-vue
# OR
yarn add -D histoire @histoire/plugin-vue

import { HstVue } from '@histoire/plugin-vue'
import { defineConfig } from 'histoire'

export default defineConfig({
  plugins: [
    HstVue(),
  ],
})

To enable interactivity in Histoire, define reactive state within your Svelte component's <script> block. Histoire automatically synchronizes this reactive data with the component's arguments. You access the Histoire context via the Hst prop.

<script lang="ts">
  import MyButton from './MyButton.svelte'

  export let Hst

  let disabled = false
  let text = ''
  let content = 'Click me!'
</script>

<Hst.Story>
  <Hst.Variant>
    <MyButton {disabled}>
      {content}
    </MyButton>

    <input bind:value={text}>
  </Hst.Variant>
</Hst.Story>

To use Histoire with Svelte 3, install the histoire core package and the @histoire/plugin-svelte plugin as development dependencies.

pnpm i -D histoire @histoire/plugin-svelte
# OR
npm i -D histoire @histoire/plugin-svelte
# OR
yarn add -D histoire @histoire/plugin-svelte

To configure Histoire, create a histoire.config.{js,ts} or .histoire.{js,ts} file at your project root. The configuration must be exported as the default export. Use the defineConfig helper from histoire for TypeScript type safety.

// histoire.config.js
import { defineConfig } from 'histoire'

export default defineConfig({
  // your Histoire configuration
})