Skip to content

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-svelte packages into your project:

shell
pnpm i -D poveste @poveste/plugin-svelte
# OR
npm i -D poveste @poveste/plugin-svelte
# OR
yarn add -D poveste @poveste/plugin-svelte

Just 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:

bash
pnpm add -D "poveste@^x.y.z" "@poveste/plugin-svelte@^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.json now 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-svelte works.
  • @latest. During the cooldown, pnpm stays on the old version.
  • The npm line. It fails inside a pnpm-installed node_modules, and with node_modules deleted 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 Svelte plugin:

ts
import { 
HstSvelte
} from '@poveste/plugin-svelte'
import {
defineConfig
} from 'poveste'
export default
defineConfig
({
plugins
: [
HstSvelte
(),
], })

Supported versions

svelte@^5.46.4 is the supported floor, alongside @sveltejs/vite-plugin-svelte@^7.3.0 — both declared as peers.

The chain is: Poveste requires Vite 8 → only @sveltejs/vite-plugin-svelte@7 peers Vite 8 → v7 requires svelte@^5.46.4. Svelte 5.0–5.46.3 cannot be assembled into a working project, which is why the floor is not ^5.0.0.

Svelte 4 is further out for the same reason: its last compatible plugin is v3, which caps at Vite 5. No release pairs Svelte 4 with the Vite we require.

The Vite config ​

Poveste builds through your project's own Vite config rather than one of its own, so a Svelte project also needs @sveltejs/vite-plugin-svelte. The block above explains which version to use; this is where it goes.

That plugin and @poveste/plugin-svelte do different jobs: one teaches Vite to compile .svelte 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 Svelte app you already have this. Starting from an empty project, without it the first build fails while reading your first component, and the error does not name the plugin you are missing.

shell
pnpm i -D vite @sveltejs/vite-plugin-svelte
# OR
npm i -D vite @sveltejs/vite-plugin-svelte
# OR
yarn add -D vite @sveltejs/vite-plugin-svelte
ts
// vite.config.ts
import { 
svelte
} from '@sveltejs/vite-plugin-svelte'
import {
defineConfig
} from 'vite'
export default
defineConfig
({
plugins
: [
svelte
(),
], })

SvelteKit already has this plugin and a vite.config.ts — see SvelteKit below, which adds Poveste to the config you have rather than creating one.

TypeScript stories ​

If you write stories with <script lang="ts">, your tsconfig.json must set verbatimModuleSyntax:

json
{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

Without it, svelte-preprocess strips imports it cannot see used — and a component referenced only from the markup looks exactly like an unused import. The story then fails to collect:

Error while collecting story src/BaseButton.story.svelte:
ReferenceError: BaseButton is not defined

svelte-preprocess warns about this at startup (The TypeScript option verbatimModuleSyntax is now required when using Svelte files with lang="ts"), but the warning is easy to miss in the middle of a collection run.

Component docs ​

A story's Docs tab shows a props, slots and events table for each .svelte component the story imports, directly or through re-exports, or names in component, read from the type on its $props() as your editor reads it, through the book's tsconfig.app.json or tsconfig.json. A component without lang="ts" is read too: an untyped let { title = 'Untitled' } = $props() documents title.

Descriptions and tags come from the props' JSDoc. A default is read from the $props() destructuring, through $bindable(...), or from a Svelte 4 export let, then from a @default tag. Props typed Snippet are slots; on* functions are events. It reads the types with a TypeScript 6 and svelte2tsx the plugin installs, so the book needs neither, whatever TypeScript it has. Props declared in installed packages are left out unless autoDocs.allow names the package, which keeps the props your own components take from a design system's types. A library's own components, such as bits-ui's, get no table, allow or not: a package is reached through its JavaScript entry, not a .svelte file. A story's own autoDocs chooses its table.

When the story renders a helper rather than the component itself, name the component:

svelte
<script lang="ts">
  import Alert from './Alert.svelte'
  import AlertDemo from './AlertDemo.svelte'

  const { Hst } = $props()
</script>

<Hst.Story title="Alert" component={Alert}>
  <AlertDemo />
</Hst.Story>

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:

json
{
  "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.

SvelteKit ​

Poveste supports SvelteKit through the same @poveste/plugin-svelte package — there is no separate SvelteKit plugin to install.

The difference is where the configuration goes. SvelteKit already owns vite.config.ts, so the tidier option is the poveste key of that file rather than a standalone poveste.config.ts; Poveste reads both and merges them. Nothing about svelte.config.js or your adapter changes.

@poveste/plugin-svelte declares @sveltejs/kit@^2.53.0 || ^3.0.0 as an optional peer: enforced when Kit is installed, ignored when it is not, since the same package serves plain Svelte. 2.53.0 is the first SvelteKit release to peer Vite 8.

The full setup, including the poveste key typing and what not to reach for when TypeScript complains, now lives on its own page: Getting started with SvelteKit.

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 Svelte stories is the page that shows one.

Community ​

If you have questions or need help, reach out to the community on GitHub Discussions.

Released under the MIT License. Updates on Bluesky and X.