Configuration
By default, the Vitebook configuration can be found at .vitebook/config.{js,cjs,mjs,ts}
. If you
followed the getting started guide then it will be set up for you
automatically. In the following sections we'll explore each of the configurable parts of
Vitebook.
Usage
The configuration file is a JavaScript (JS) or TypeScript (TS) file that must contain a
default
export binding to a plain JS object export default { ... }
. The @vitebook/client
package exports a helper function defineConfig
to ensure TypeScript type checking is applied.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
// ...
});
The Vitebook configuration file is used in a Node environment, so ensure:
- No browser-specific API's are used.
- When importing from Vitebook packages, use the Node distribution by specifying the
/node
exports path, such asimport { ... } from '@vitebook/client/node'
. - Vitebook is ESM only, however if you require CommonJS you can use a
.ts
file and ESBuild will transpile it correctly (we polyfill CommonJS globals such asrequire
,__dirname
, etc.).
Directories
The following directories can be configured when using Vitebook:
root
: The project root directory path, defaults toprocess.cwd()
. The path can be absolute or relative to the current working directory. During development Vitebook is a Node server, thus files are resovled from the root such as/images/image.png
.srcDir
: The source code directory path, defaults to<root>/src
. The value can be either an absolute file system path, or a path relative to<root>
. Currently, this is only used to auto-resolve page routes so instead of/src/components/button.html
, we get/components/button.html
.configDir
: The Vitebook configuration directory path, defaults to<root>/.vitebook
. The value can be either an absolute file system path, or a path relative to<root>
.publicDir
: Directory to serve as plain static assets, defaults to<configDir>/public
. Files in this directory are served and copied to theoutDir
directory as-is without any transformations. The value can be either an absolute file system path, or a path relative to<configDir>
.outDir
: The production build output directory path, defaults to<configDir>/dist
. The value can be either an absolute file system path, or a path relative to<configDir>
.cacheDir
: The Vitebook cache directory path, defaults to<configDir>/.cache
. Mainly used by Vite for dependency prebundling. The value can be either an absolute file system path, or a path relative to <configDir>
.tmpDir
: The Vitebook temporary directory path, defaults to<configDir>/.temp
. As the name suggests, used to store temporary files. This directory is reset if it becomes larger than 10MB. The value can be either an absolute file system path, or a path relative to<configDir>
.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
root: '.',
srcDir: 'src',
configDir: '.vitebook',
publicDir: '.vitebook/public',
outDir: '.vitebook/dist',
cacheDir: '.vitebook/.cache',
tmpDir: '.vitebook/.temp',
});
Pages
The include
configuration option specifies the files you'd like to include in your Vitebook
application. The option accepts a list of globs
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
include: ['src/**/*.md'],
});
Site
Site-wide options for setting the base language, document title, description, locales, etc. This
metadata is available to all themes via the @vitebook/client
package.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
site: {
baseUrl: '/',
lang: 'en-US',
title: 'Vitebook',
description: 'Blazing fast alternative to Storybook.',
head: [],
theme: {
// ...
},
locales: {
// ...
},
},
});
Site Head
Site configuration option for specifying HTML tags to be inserted in the document <head>
. Each
tag is described as a tuple with the first index being the tag name, the second an object
of attributes denoted by { [attrName]: attrValue }
, and the third index (optional) being any
inner HTML.
TIP
If the head tags you're inserting don't require dynamic processing, simply include them in the
index.html
file present in your Vitebook configuration directory.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
site: {
head: [
['link', { rel: 'icon', href: '/logo.png' }],
['script', { src: 'https://site.com/script.js', type: 'module' }],
['style', { type: 'text/css' }, 'p { color: red; }'],
],
},
});
Site Theme
The theme
configuration object depends on the specific theme being used. Vitebook provides a
default theme out of the box, see the documentation on it
for more information.
- JavaScript
- TypeScript
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
site: {
/** @type {(import('@vitebook/theme-default/node').DefaultThemeConfig} */
theme: {
// ...
},
},
});
import { defineConfig } from '@vitebook/client/node';
import { DefaultThemeConfig } from '@vitebook/theme-default/node';
export default defineConfig<DefaultThemeConfig>({
site: {
theme: {
// ...
},
},
});
Site Locales
The locales
option is used to specify locale specific site settings.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
site: {
locales: {
'/': {
lang: 'en-US',
langLabel: 'English',
title: 'Vitebook',
description: 'Storybook alternative.',
head: [],
},
'/zh': {
lang: 'zh-CN',
langLabel: 'Chinese',
title: '快速地 书',
description: 'Storybook 选择.',
head: [],
},
},
},
});
Alias
Specifies an object, or an array of objects, which defines aliases used to replace values
in import
or require
statements. With either format, the order of the entries is important,
in that the first defined rules are applied first.
- This is simply shorthand for
vite.resolve.alias
. - This is passed to
@rollup/plugin-alias
as the "entries" field.
See the @rollup/plugin-alias
import path from 'path';
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
alias: {
'~src': path.resolve(__dirname, '../src'),
// ...
},
});
Vite
Used to set Vite configurationvite.config.{js,ts}
file at the project root. If you require overriding some
configuration options, simply override them here.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
vite: {
// ...
},
});
Plugins
The plugins
property specifies the plugins to be used. Similarly to Vite and Rollup, falsy
plugins are ignored, and arrays of plugins are flattened. Vitebook, Vite, and Rollup plugins are
accepted.
A client plugin is the only required plugin for Vitebook to function as it sets up a client/server
entry file. The Vitebook client plugin is exported from the @vitebook/client
package.
Important to keep in mind that Vitebook plugins are simply an extension of Vite plugins which are an extension of Rollup plugins. By extension, we simply mean additional plugin hooks are available. The following resources are perfect for diving deeper into plugins:
import { clientPlugin, defineConfig } from '@vitebook/client/node';
import { defaultThemePlugin } from '@vitebook/theme-default/node';
export default defineConfig({
plugins: [clientPlugin(), defaultThemePlugin()],
});
Routes
By default, Vitebook handles file path to application route resolution. You can use the resolveRoute
option to override routing to specific, or all file paths.
- The
resolveRoute
function maps file paths to client routes such assrc/button/button.story.ts
tobutton/button.html
. - The
resolveRoute
function can returnnull
orundefined
to fallback to the default Vitebook route resolver. - The returned route must end with
.html
. - Plugins can override application-level routing provided by Vitebook, or values returned from the
resolveRoute
function.
import { defineConfig } from '@vitebook/client/node';
export default defineConfig({
resolveRoute({ filePath, relativeFilePath }) {
// ...
},
});