Learn more about configuring Histoire here.
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(),
],
})
string
- Default: '.histoire/dist'
Output directory.
export default defineConfig({
outDir: '.histoire/dist',
})
string[]
- Default: ['**/*.story.vue']
Glob patterns for story files to include.
export default defineConfig({
storyMatch: [
'**/*.story.vue',
],
})
string[]
- Default: [ '**/node_modules/**', '**/dist/**' ]
Glob patterns to ignore files while searching for story files.
export default defineConfig({
storyIgnored: [
'**/node_modules/**',
'**/dist/**',
],
})
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',
},
})
Object
Customize the look of the book.
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 thepublic
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
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',
},
})
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.
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.
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,
},
})
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,
},
],
})
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);
}
boolean
- Default: false
Automatically apply the contrast color to the story preview text.
export default defineConfig({
autoApplyContrastColor: true,
})
string
- Default: 'dark'
Class added to the html root of the story preview when dark mode is enabled.
export default defineConfig({
sandboxDarkClass: 'my-dark-class',
})
(md: MarkdownIt) => MarkdownIt | Promise<MarkdownIt>
Customize the markdown-it renderer.
export default defineConfig({
markdown: (md) => {
md.use(SomeMarkdownItPlugin)
},
})
'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',
})
ViteConfig | ((config: ViteConfig, env: ViteConfigEnv) => void | ViteConfig | Promise<void | ViteConfig>)
Vite config override.
export default defineConfig({
vite: {
server: {
port: 3042,
},
},
})
string[]
List of Vite plugin names to exclude for Histoire.
export default defineConfig({
viteIgnorePlugins: [
'vite-plugin-svelte-kit',
],
})
{ web?, ssr? }
Determine the transform method of modules
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.
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$/],
},
})
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:
{{ viteNodeInlineDepsError }}
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/,
],
})