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-vue

Just installed and got an older version?

For about a day after a release, pnpm installs the previous version and says so only in passing — + poveste x.y.z (x.y.z is available), with no error and no warning. That is pnpm's release-age cooldown holding back anything published in the last 24 hours, not a broken publish. Use the npm line above, wait it out, or pass --config.minimum-release-age=0 — the kebab-case spelling, because pnpm 12 accepts the camelCase one and silently ignores it. Asking for the exact version does not get you past it: pnpm 12 refuses a version inside the window too, with ERR_PNPM_NO_MATURE_MATCHING_VERSION.

Poveste needs Node >=24.15.0, and npm will not tell you

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, and on a recent Node the only warning it prints names a dependency, not Poveste. These docs then 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.

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-reload
• poveste build: builds the app for production
• poveste 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

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.