This module provides a Storybook-like experience for Nuxt components
npm install nuxt-componentsbook-module.stories.vue files. It automatically scans a specified directory for story files, generates dynamic routes, and creates an interactive UI for viewing and testing components.Unlike Storybook, which can be complex and heavy, this module is lightweight and seamlessly integrates into Nuxt, making it easy to set up and use. All stories are written as standard Vue components, ensuring a smooth and intuitive development experience.
.stories.vue files and registration as pages.EnhancedPreview.bash
npm install --save-dev nuxt-componentsbook-module
`or
bash
yarn add --dev nuxt-componentsbook-module
`Setup
$3
Add the module to your :`ts
export default defineNuxtConfig({
modules: [
'nuxt-componentsbook-module',
],
componentsBook: {
// Directory where .stories.vue files are located:
componentsDir: 'components',
disabled: false,
cache: true,
},
})
`$3
To document a component, create a file in your components directory:#### MyInput.stories.vue (Example with
EnhancedPreview)`vue
🟢 CustomInput Component
The CustomInput component is a versatile input field with multiple configurations.
đź› Interactive Controls
🔹 Preview
:component="CustomInput"
:props="{ label, type, placeholder, disabled, readonly, 'helper-text': helperText, size }"
:emits="['click']"
@click="console.log('Clicked!')"
/>
`$3
Start your Nuxt development server:bash
npm run dev
`Visit
in your browser to see the list of stories.---
Using
EnhancedPreviewThe
component is the recommended way to embed and test your components interactively. It allows for:- Dynamic prop manipulation (via either your own UI or the optional built-in Props Editor)
- Event handling (e.g.,
@click="...")
- Slots usage (e.g., or other named slots)
- v-model binding
- Automatic code snippet generation for copy-paste usage examples$3
`vue
:component="CustomInput"
:props="{
label: 'Enter Text',
type: 'text',
placeholder: 'Type something...',
disabled: false,
readonly: false,
'helper-text': 'This is a helper text.',
size: 'md',
}"
:emits="['click']"
@click="handleClick"
>
test slot
`-
automatically binds the parent’s modelValue ref.
- :props passes other props directly to the component.
- :emits declares which events the component might emit.
- The slot #append is injected into if your component uses it.---
componentPropsMeta for Automatic Props EditingYou can optionally provide
componentPropsMeta to each . This activates an inline props editor () where each prop is automatically mapped to a text field, select, checkbox, or number input.$3
For each prop, specify a
fieldType:-
text → a simple text
- → a Now you have two ways to set props: manually via your own inputs, or via the auto-generated editor. They both affect the same variables.
$3
If you need other field types (like color pickers, sliders, multiple checkboxes, etc.), you can fork or extend the
to handle them. The module itself provides a basic structure, but you have full control to expand it.---
Advanced Usage:
useEnhancedPreviewFor users needing complete control—like custom watchers, advanced store bindings, or specialized events—the
composable is available. It:
- Lets you dynamically attach listeners or v-model watchers.
- Returns a renderedComponent you can put anywhere.
- Generates code snippets, can freeze/unfreeze them, etc.Below is a short summary (for deeper details, see the Advanced Examples):
`ts
import { useEnhancedPreview } from 'nuxt-componentsbook-module'
// ...
const {
renderedComponent,
generatedCode,
isFrozen,
toggleFreeze,
copyCode
} = useEnhancedPreview(myProps, myEmit, {
fullVueFile: true,
kebabCase: true,
// ...
})
`Then in your template:
vue
`---
How It Works
1. The module scans the specified for .stories.vue files.
2. Generates dynamic Vue pages for each story and registers them with Nuxt.
3. Provides a UI layout for previewing and testing components interactively.
4. Supports real-time editing with automatic updates when files are modified.
5. Enhances DevTools, adding a Components Book tab for quick navigation.---
nuxt-i18n-micro Integration
When using nuxt-i18n-micro, you might want to ensure that locale prefixes (like
/en/) are not applied to the Components Book routes. Doing so can break the generated routes. Therefore:1. Load
nuxt-componentsbook-module first
2. Load nuxt-i18n-micro secondin your
nuxt.config.ts:`ts
export default defineNuxtConfig({
modules: [
'nuxt-componentsbook-module', // order matters
'nuxt-i18n-micro',
],
})
`---
đź› DevTools Integration
When running in development mode, a Components Book tab appears in Nuxt DevTools, providing an iframe-based UI for exploring stories. It offers a quick overview of all
files, letting you jump directly to a desired component’s page.---
More Resources
- Live Demo – See the module in action.
- Usage Examples – Additional .stories.vue` files for more patterns and ideas.---
Enjoy a lighter, simpler alternative to Storybook directly inside your Nuxt application!