Skip to content

Getting started with Solid ​

Installation ​

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

You also need solid-js@^1.9.0 and vite-plugin-solid@^2.11.0, which a Solid project built with Vite already has.

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-solid@^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-solid 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.

Configuration ​

Keep vite-plugin-solid in your Vite config — Poveste reads it, so story files compile the way your components do:

ts
// vite.config.ts
import { 
defineConfig
} from 'vite'
import
solid
from 'vite-plugin-solid'
export default
defineConfig
({
plugins
: [
solid
()],
})

Then add the plugin. It tells Poveste that .story.tsx and .story.jsx files are stories, alongside any .story.vue or .story.svelte your book already has. React stories are .story.tsx files too, so in a book with both, each goes to the plugin it imports defineStory from: see More than one framework in a book.

ts
// poveste.config.ts
import { 
HstSolid
} from '@poveste/plugin-solid'
import {
defineConfig
} from 'poveste'
export default
defineConfig
({
plugins
: [
HstSolid
()],
})

Write a story ​

A story is a .story.tsx file whose default export describes it. Each variant has a render that returns JSX. Badge stands in for a component of your own; to follow along as written, this one is enough:

tsx
// src/Badge.tsx
import type { JSX } from 'solid-js'

export function 
Badge
(
props
: {
tone
: 'info' | 'warn',
children
: JSX.
Element
}) {
return <
span
class
={`badge badge-${
props
.
tone
}`}>{
props
.
children
}</
span
>
}
tsx
// src/Badge.story.tsx
import { 
defineStory
} from '@poveste/plugin-solid'
import {
Badge
} from './Badge'
export default
defineStory
({
title
: 'Badge',
variants
: [
{
title
: 'Info',
render
: () => <
Badge
tone
="info">Information</
Badge
> },
{
title
: 'Warning',
render
: () => <
Badge
tone
="warn">Careful</
Badge
> },
], })

A story with no variants and a render of its own has one implicit variant. id, group, icon, layout and source work as they do for the other frameworks.

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.

Component docs ​

Name the component a story documents in its component field, and its docs tab shows a props, slots and events table read from the type of the component's first parameter:

tsx
export default 
defineStory
({
title
: 'Badge',
component
:
Badge
,
variants
: [/* ... */],
})

Descriptions and tags come from the props' JSDoc. A default is read from the object passed before props to mergeProps, or from a destructured parameter, then from a @default tag. Props typed JSX.Element, and children taken through ParentProps or FlowProps, are slots; on* functions are events. The children every element's attributes declare is left out with the rest of them. It reads the types with a TypeScript 6 Poveste installs, whatever TypeScript the book has, including the TypeScript 7 Vite's solid-ts template installs or none at all, and reads the book's tsconfig.app.json or tsconfig.json. Props declared in installed packages are left out unless autoDocs.allow names the package, such as @kobalte/core.

component takes one component, not a list. A story without it gets no table, and its Docs tab says why unless the story has docs of its own. A story that names a library's component, such as one from @kobalte/core, shows the component's name and no rows until allow names the package, because every prop it has is declared there.

A story's autoDocs field chooses its own table: false for none, or a list of the sections to show, such as ['props', 'events']. See autoDocs.

State ​

Give a story or a variant an initState, and render receives that state and a way to change it. Counter again stands in for your own component:

tsx
// src/Counter.tsx
export function 
Counter
(
props
: {
count
: number,
onIncrement
: () => void }) {
return <
button
onClick
={
props
.
onIncrement
}>{`Count: ${
props
.
count
}`}</
button
>
}
tsx
// src/Counter.story.tsx
import { 
defineStory
} from '@poveste/plugin-solid'
import {
Counter
} from './Counter'
export default
defineStory
<{
count
: number }>({
title
: 'Counter',
initState
: () => ({
count
: 0 }),
variants
: [
{
title
: 'From zero',
render
: ({
state
,
setState
}) => (
<
Counter
count
={
state
.
count
}
onIncrement
={() =>
setState
('count',
c
=>
c
+ 1)} />
), }, {
title
: 'From ten',
initState
: () => ({
count
: 10 }),
render
: ({
state
,
setState
}) => (
<
Counter
count
={
state
.
count
}
onIncrement
={() =>
setState
('count',
c
=>
c
+ 1)} />
), }, ], })

render runs once, as a Solid component does. state is a Solid store, so reading state.count inside the JSX is what keeps the output current — read it outside, at the top of render, and the value is fixed at the first render. setState is the store's setter, with the same path syntax.

The state editor shows the state and lets you edit it, and an edit reaches the story without running render again. A variant's own initState takes precedence over the story's.

Setup and wrappers ​

Export setupSolid from your setup file to run code before every story mounts. addWrapper puts a component around each one — a theme provider, a layout frame, a context:

tsx
// src/poveste.setup.tsx
import { 
defineSetupSolid
} from '@poveste/plugin-solid'
export const
setupSolid
=
defineSetupSolid
(({
addWrapper
}) => {
addWrapper
(
props
=> <
div
class
="story-frame">{
props
.
children
}</
div
>)
})
ts
// poveste.config.ts
export default 
defineConfig
({
plugins
: [
HstSolid
()],
setupFile
: '/src/poveste.setup.tsx',
})

The hook runs before the story mounts, so a wrapper is there for the first render. The first wrapper added is the outermost. A variant can set its own setupApp, called after the global hook with the same argument: { story, variant, addWrapper }.

Source ​

The Source panel's Dynamic view prints what a variant's render returns, as JSX, with each value as it is now, and follows the state as the panel or the story changes it:

<Counter count={10} label="Clicked" onIncrement={…} />

A function prop or child prints as {…}, and so does a class instance. A Date, Map, Set or regular expression prints as code that makes the same value, including inside an object or an array. A variant's own source string replaces the generated code, and Static shows the story file.

Solid's JSX compiles to DOM operations and leaves no tree to read, so Poveste compiles the story file a second time, when the panel first asks, with its JSX building plain elements. render runs again for that, with no preview behind it, so a side effect in render itself runs again too. A signal or a store it creates starts from its first value. A render that returns something other than JSX, such as a solid-js/html template, has nothing to print, and the panel opens on Static.

A component prints by its runtime name, so one with no name that can be written as a tag, such as const Card = wrap(() => …), leaves the panel on Static, and the Dynamic button's tooltip says why. Give it a capitalized name, or set displayName on it.

What is not here yet ​

  • Controls. A variant with initState gets the state editor; one without says there is nothing to show. Controls built from your components — explicit ones and props detected automatically — come in later releases.

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