Node.js API

Initialization

First, you need to initialize the API for your style guide config.

Using a JavaScript object:

import styleguidist from 'vite-styleguidist'
const styleguide = styleguidist({
  logger: {
    warn: console.warn,
    info: console.log,
    debug: console.log
  },
  components: './lib/components/**/*.js',
  viteConfig: {
    resolve: {
      alias: {
        '@': new URL('./src', import.meta.url).pathname
      }
    }
  }
})

info

Any output is disabled by default, you may need to define your own logger.

Using a config file:

import styleguidist from 'vite-styleguidist'
const styleguide = styleguidist('../styleguide.config.js')

Or auto searching a config file:

import styleguidist from 'vite-styleguidist'
const styleguide = styleguidist()

See all available config options.

info

Styleguidist is an ES module. CommonJS code can still require('vite-styleguidist') on the supported Node.js versions (22.12 or newer; Node 23 is not supported, 24 and later are, see Compatibility), the result is the same styleguidist function.

Methods

build([callback])

Arguments

1. [callback(err, config, output)] (Function): A callback to be invoked when style guide is built:

   1. err (Object): error details.
   2. config (Object): normalized style guide config.
   3. output (Object): Vite build output (the list of generated chunks and assets).

Returns

(Promise): resolves to the Vite build output. Without a callback, the promise rejects when the build fails; with a callback, the error is passed to the callback instead.

Example

import styleguidist from 'vite-styleguidist'
const styleguide = styleguidist('../styleguide.config.js')
await styleguide.build()
console.log(
  'Style guide published to',
  styleguide.config.styleguideDir
)

server([callback])

Arguments

1. [callback(err, config, server)] (Function): A callback to be invoked when the dev server is listening:

   1. err (Object): error details.
   2. config (Object): normalized style guide config.
   3. server (Object): the ViteDevServer instance.

Returns

(Promise): resolves to the ViteDevServer instance, already listening. Use server.resolvedUrls to get its URLs and server.close() to stop it.

Example

import styleguidist from 'vite-styleguidist'
const server = await styleguidist('../styleguide.config.js').server()
console.log(`Listening at ${server.resolvedUrls.local[0]}`)

makeViteConfig([env])

Arguments

1. [env='production'] (String): production or development.

Returns

(Promise): resolves to the Vite inline config Styleguidist would use, including your viteConfig (or vite.config.js) and the Styleguidist plugins.

Example

import { createServer } from 'vite'
import styleguidist from 'vite-styleguidist'

const config = await styleguidist().makeViteConfig('development')
const server = await createServer(config)
await server.listen()

config

(Object): the normalized style guide config, with defaults applied and paths resolved.

defineConfig(config)

An identity function that types a config file: it returns config untouched, and TypeScript checks it against StyleguidistConfig on the way through. Use it in a TypeScript config file, where the object has no type of its own to be checked against:

// styleguide.config.ts
import { defineConfig } from 'vite-styleguidist'

export default defineConfig({
  title: 'My Style Guide',
  components: 'src/components/**/*.tsx'
})

A JavaScript config file gets the same checking from a type comment instead, with no import at all — see type checking your config.

Types

The package ships its own TypeScript declarations; these are the ones a config file or a script around the Node.js API is likely to name:

Type	What it is
StyleguidistConfig	A config file: every option, all of them optional
SanitizedStyleguidistConfig	The normalized config: what the config property above, and every callback, receives
ConfigSection	One entry of the sections option
Theme	Every theme token, all of them set
RecursivePartial<T>	The same with everything optional, which is what the theme option takes
Styles	The styles option (JSS’s own type)
ColorScheme	The colorScheme option
StyleguidistEnv	development or production, the argument of viteConfig and makeViteConfig

import type {
  RecursivePartial,
  StyleguidistConfig,
  Theme
} from 'vite-styleguidist'

const theme: RecursivePartial<Theme> = { color: { link: 'tomato' } }

export const config: StyleguidistConfig = { theme }