Getting started with Poveste
Overview
poveste is the Romanian word for "story", pronounced
/poˈveste/(po-VES-teh) . Coming from histoire? See the migration guide.
Poveste is a tool to generate stories applications (or "books").
Learn more about Poveste here »
Installation
Install the poveste and @poveste/plugin-vue packages into your project:
pnpm i -D poveste @poveste/plugin-vue
# OR
npm i -D poveste @poveste/plugin-vue
# OR
yarn add -D poveste @poveste/plugin-vueJust installed and got an older version?
For about a day after a release, pnpm installs the previous version, with no error. That's pnpm's release-age cooldown, not a broken publish. Check what landed with pnpm list poveste, because the install may not say: pnpm 11.5.3 adds (x.y.z is available) to its output, and 11.28.9 and 12.16.1 print nothing. A plugin that's new in that release is worse off: nothing comes before its 0.0.1 placeholder, which has no code, so pnpm installs that beside the previous poveste, and the only sign is a deprecated warning.
To get the new version, whether or not you've already installed, name it. npm view poveste version prints it:
pnpm add -D "poveste@^x.y.z" "@poveste/plugin-vue@^x.y.z"pnpm installs them and lists them under minimumReleaseAgeExclude in a pnpm-workspace.yaml it creates. Commit that file, so later installs and CI accept them too.
These don't get you there once the old version is in package.json:
- The install line again.
package.jsonnow says the old^x.y.z, and pnpm keeps it, even after the cooldown. Once the cooldown has passed,pnpm up -L poveste @poveste/plugin-vueworks. @latest. During the cooldown, pnpm stays on the old version.- The
npmline. It fails inside a pnpm-installednode_modules, and withnode_modulesdeleted it installs the old version again. It only helps a project with no Poveste yet.
Avoid --config.minimum-release-age=0. With a named version or pnpm up -L it does install the new one, but then every later pnpm i, in CI too, fails until the cooldown passes, because the lockfile holds versions the cooldown rejects. That includes a project with no Poveste yet.
Poveste needs Node >=22.22.2, and npm installs an old version instead
Run node -v before you install. On an older Node, npm i poveste still succeeds: npm installs the newest earlier Poveste that accepts your Node, which can be a long way back. On Node 22.21.1 and 20.19.0 that's 0.6.1. Expect a block of npm warn EBADENGINE warnings first, about dependencies such as jsdom, none of them naming Poveste. The lines that do name it come after: npm warn deprecated on six Poveste packages, each saying to install @latest, so update Node and do that. These docs otherwise describe a version you do not have, and the difference looks like a bug rather than its cause. With engine-strict=true in your .npmrc, npm refuses with EBADENGINE instead. pnpm installs the current version, and Poveste then refuses to start, naming the Node it needs; Yarn 1 refuses to install.
On Node 24, prefer 24.15 or later. Poveste's DOM dependency, jsdom, and three of its own dependencies declare ^22.22.2 || ^24.15.0 || >=26. On 24.13.0 npm warns EBADENGINE for each of them and installs anyway, and a Vue book built there, but nothing tests Poveste on a Node 24 before 24.15.
Create a poveste.config.js or poveste.config.ts file in your project root to enable the Vue plugin:
import { HstVue } from '@poveste/plugin-vue'
import { defineConfig } from 'poveste'
export default defineConfig({
plugins: [
HstVue(),
],
})The Vite config
Poveste builds through your project's own Vite config rather than one of its own, so a Vue project also needs @vitejs/plugin-vue. That is a different package from @poveste/plugin-vue, doing a different job: one teaches Vite to compile .vue files, the other teaches Poveste to collect and render stories. Installing the second does not bring the first.
If you are adding Poveste to an existing Vue app you already have this, and there is nothing to do here. Starting from an empty project, without it the first build fails on the first component it reads:
Failed to parse source for import analysis…
Install @vitejs/plugin-vue to handle .vue files.pnpm i -D vite @vitejs/plugin-vue
# OR
npm i -D vite @vitejs/plugin-vue
# OR
yarn add -D vite @vitejs/plugin-vue// vite.config.ts
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
vue(),
],
})Command Line Interface
Poveste provides the following commands:
poveste dev: starts a development server with hot-reloadpoveste build: builds the app for productionpoveste preview: starts an HTTP server that serves the built app
You can add these to your package.json like this:
{
"scripts": {
"story:dev": "poveste dev",
"story:build": "poveste build",
"story:preview": "poveste 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 poveste --help in your project.
Running several books at once is fine: give each poveste dev a distinct --port and the servers stay fully isolated, hot-reload included.
TypeScript
The props, slots and events table on a story's Docs tab is read from your components' types with a TypeScript 6 Poveste installs, so the book needs none of its own, whatever version it has. See Props, slots and events.
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.
/// <reference types="@poveste/plugin-vue/components" />And add it in the include field of your tsconfig.json.
Example:
{
"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
Poveste supports Nuxt with the @poveste/plugin-nuxt package, which sits on top of @poveste/plugin-vue rather than replacing it — a Nuxt project installs three packages and registers both plugins.
Nuxt 4.5 is the supported floor (nuxt@^4.5.0): the first Nuxt whose @nuxt/vite-builder runs on Vite 8, which Poveste requires. Nuxt 4.0–4.4 are on Vite 7 and out of range for the same reason, and Nuxt 3 is out of the peer range because no example or CI job ever covered it.
Unlike a plain Vue project, Nuxt needs no vite.config.ts — its own builder supplies the Vue plugin, and @poveste/plugin-nuxt reads Nuxt's resolved Vite config and curates it for the story sandbox.
The full setup, the i18n notes and the incompatible-client-plugins guidance now live on their own page: Getting started with Nuxt.
Configuration
Learn more about configuring Poveste here.
Write your first story
Poveste has nothing to show until a story file exists, and poveste build on a book without one says so rather than failing.
Writing Vue stories is the page that shows one.
Community
If you have questions or need help, reach out to the community on GitHub Discussions.