Skip to content

Getting started with Histoire

Overview

Histoire is the French word for "Story" and is pronounced /is.twaʁ/, like "is·twar"

Histoire is a tool to generate stories applications (or "books").

Learn more about Histoire here »

Sponsors

Histoire is an Open-Source project supported by our sponsors - thank you!

See our sponsors »

Installation

Install the histoire and @histoire/plugin-vue packages into your project:

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

Create an histoire.config.js or histoire.config.ts file in your project root to enable the Vue plugin:

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

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

Command Line Interface

Histoire provides the following commands:

  • histoire dev: starts a development server with hot-reload
  • histoire build: builds the app for production
  • histoire preview: starts an HTTP server that serves the built app

You can add these to your package.json like this:

json
{
  "scripts": {
    "story:dev": "histoire dev",
    "story:build": "histoire build",
    "story:preview": "histoire preview"
  }
}

And then run them with npm run story:dev or npm run story:build.

You can specify additional CLI options like --port. For a full list of CLI options, run npx histoire --help in your project.

TypeScript

To enable the global components types in your project, create an env.d.ts file at the root of your project if it doesn't already exist.

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

And add it in the include field of your tsconfig.json.

Example:

json
{
  "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"
  ]
}

Nuxt

Histoire supports Nuxt 3 with the @histoire/plugin-nuxt package.

bash
pnpm add -D @histoire/plugin-nuxt

Add the plugin in histoire config:

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

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

Configuration

Learn more about configuring Histoire here.

Community

If you have questions or need help, reach out to the community at Discord and GitHub Discussions.

Released under the MIT License.