Configuration Reference #

Learn more about configuring Histoire here.

plugins #

Array of plugins. Learn more about official plugins and how to develop them.

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

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

outDir #

string - Default: '.histoire/dist'

Output directory.

export default defineConfig({
  outDir: '.histoire/dist',
})

storyMatch #

string[] - Default: ['**/*.story.vue']

Glob patterns for story files to include.

export default defineConfig({
  storyMatch: [
    '**/*.story.vue',
  ],
})

Use src/**/*.story.vue to prevent search errors in binary files (e.g., in iOS or Android folders) when using Ionic Capacitor.

storyIgnored #

string[] - Default: [ '**/node_modules/**', '**/dist/**' ]

Glob patterns to ignore files while searching for story files.

export default defineConfig({
  storyIgnored: [
    '**/node_modules/**',
    '**/dist/**',
  ],
})

tree #

Object - Default: { file: 'title', order: 'asc' }

How to generate the story tree.

Learn more: Vue 3

Properties:

• file: 'title' | 'path' | ((file: TreeFile) => string[]): How to get the path of a story.
• order: 'asc' | ((a: string, b: string) => number): How to sort the stories.

export default defineConfig({
  tree: {
    file: 'title',
    order: 'asc',
  },
})

theme #

Object

Customize the look of the book.

Learn more

Properties:

• title: string: Main page title. For example: 'Acme Inc.'
• logo: Object: Logo configuration.
  • square: string: Square logo image without text.
  • light: string: Full logo for light theme.
  • dark: string: Full logo for dark theme.
• favicon: string: Href to the favicon file (not processed by Vite). Put the file in the public directory.
• colors: Object: Customize the colors. Each color should be an object with shades as keys.
• logoHref: string: Add a link to the main logo
• darkClass: string: Class added to the story preview when dark mode is enabled (default is 'dark').
• defaultColorScheme: 'light' | 'dark' | 'auto': Default color scheme for the app. 'auto' will use the system preference.
• hideColorSchemeSwitch: boolean: Hides the dark mode button in the toolbar.
• storeColorScheme: boolean: Enable persistence of the color scheme in the browser's local storage.

import { defaultColors } from 'histoire'

export default defineConfig({
  theme: {
    title: 'Acme Design System',
    favicon: '/my-favicon.svg',
    logo: {
      square: '/src/img/logo-square.svg',
      light: '/src/img/logo-light.svg',
      dark: '/src/img/logo-dark.svg',
    },
    colors: {
      primary: defaultColors.cyan,
    },
    logoHref: 'https://acme.com',
    defaultColorScheme: 'light',
    hideColorSchemeSwitch: true,
    storeColorScheme: false,
  },
})

setupFile #

string | { browser: string, server: string }

Setup file exporting a default function executed when setting up each story preview.

Import custom CSS files from this file.

Learn more

export default defineConfig({
  setupFile: '/src/histoire-setup.ts',
})

If you need a different version for the NodeJS server (while collecting stories), you can use an object:

export default defineConfig({
  setupFile: {
    browser: '/src/histoire-setup.ts',
    server: '/src/histoire-setup.server.ts',
  },
})

This can be useful if you need to exclude some imported libraries that only works in the browser.

defaultStoryProps #

Object

Default values for story props.

export default defineConfig({
  defaultStoryProps: {
    icon: 'carbon:assembly-reference',
    iconColor: '#00c5a5',
    layout: {
      type: 'grid',
      width: 300,
    },
    responsiveDisabled: true,
    autoPropsDisabled: true,
  },
})

responsivePresets #

Array

Predefined responsive sizes for story playgrounds.

Each object in the array is a preset with the following properties:

• label: string: Label for the preset.
• width: number: Width of the preset (pixels).
• height: number: Height of the preset (pixels).

Default values are shown in the example below:

export default defineConfig({
  responsivePresets: [
    {
      label: 'Mobile (Small)',
      width: 320,
      height: 560,
    },
    {
      label: 'Mobile (Medium)',
      width: 360,
      height: 640,
    },
    {
      label: 'Mobile (Large)',
      width: 414,
      height: 896,
    },
    {
      label: 'Tablet',
      width: 768,
      height: 1024,
    },
    {
      label: 'Laptop (Small)',
      width: 1024,
      height: null,
    },
    {
      label: 'Laptop (Large)',
      width: 1366,
      height: null,
    },
    {
      label: 'Desktop',
      width: 1920,
      height: null,
    },
    {
      label: '4K',
      width: 3840,
      height: null,
    },
  ],
})

backgroundPresets #

Array

Background color of the story preview.

Each object in the array is a preset with the following properties:

• label: string: Label for the preset.
• color: string: Color of the preset.
• contrastColor?: string: Contrast color of preset

Default values are shown in the example below:

export default defineConfig({
  backgroundPresets: [
    {
      label: 'Transparent',
      color: 'transparent',
      contrastColor: '#333'
    },
    {
      label: 'White',
      color: '#fff',
      contrastColor: '#333'
    },
    {
      label: 'Light gray',
      color: '#aaa',
      contrastColor: '#eee'
    },
    {
      label: 'Dark gray',
      color: '#333',
      contrastColor: '#ccc'
    },
    {
      label: 'Black',
      color: '#000',
      contrastColor: '#fff'
    },
  ],
})

You can use current contrast color via the css variable --histoire-contrast-color:

.my-class {
  color: var(--histoire-contrast-color);
}

autoApplyContrastColor #

boolean - Default: false

Automatically apply the contrast color to the story preview text.

export default defineConfig({
  autoApplyContrastColor: true,
})

markdown #

(md: MarkdownIt) => MarkdownIt | Promise<MarkdownIt>

Customize the markdown-it renderer.

export default defineConfig({
  markdown: (md) => {
    md.use(SomeMarkdownItPlugin)
  },
})

routerMode #

'history' | 'hash' - Default: 'history'

Changes the router mode:

• 'history': HTML 5 history mode with cleaner URLs.
• 'hash': Use the hashtag hack in the URL to support more servers and static hosting services.

export default defineConfig({
  routerMode: 'hash',
})

vite #

ViteConfig | ((config: ViteConfig, env: ViteConfigEnv) => void | ViteConfig | Promise<void | ViteConfig>)

Vite config override.

export default defineConfig({
  vite: {
    server: {
      port: 3042,
    },
  },
})

viteIgnorePlugins #

string[]

List of Vite plugin names to exclude for Histoire.

export default defineConfig({
  viteIgnorePlugins: [
    'vite-plugin-example',
  ],
})

viteNodeTransformMode #

{ web?, ssr? }

Determine the transform method of modules

viteNodeTransformMode.ssr #

RegExp[] - Default: [/\.([cm]?[jt]sx?|json)$/]

Use SSR transform pipeline for the specified files.
Vite plugins will receive ssr: true flag when processing those files.

viteNodeTransformMode.web #

RegExp[] - Default: modules other than those specified in transformMode.ssr

First do a normal transform pipeline (targeting browser), then do a SSR rewrite to run the code in Node.
Vite plugins will receive ssr: false flag when processing those files.

When you use JSX as component models other than React (e.g. Vue JSX or SolidJS), you might want to config as following to make .tsx / .jsx transformed as client-side components:

export default defineConfig({
  viteNodeTransformMode: {
    web: [/\.[jt]sx$/],
  },
})

viteNodeInlineDeps #

RegExp[]

Transpile dependencies when collecting stories on Node.js.

For example, if you have a dependency that contains ESM code but Node tries to load it in CommonJS context, you might have this kind of error:

.../my-project/node_modules/.pnpm/some-library@1.0.0/lib/esm/index.js:3
export function foo() {
^^^^^^

SyntaxError: Unexpected token 'export'
    at Object.compileFunction (node:vm:352:18)
    at wrapSafe (node:internal/modules/cjs/loader:1031:15)
    ...

We can see that the some-library (made-up name) is misconfigured and Node treats it as CommonJS code (the cjs/loader is being used) but it contains ESM code. Hence the error.

export default defineConfig({
  viteNodeInlineDeps: [
    /some-library/,
  ],
})

collectMaxThreads #

number - Default: available cpus

Number of maximum threads used to collect stories (both for development and building). Threads count will never go above this limit but might be lower.

export default defineConfig({
  collectMaxThreads: 4,
})