Repository navigation
v0.23.0
A story's docs can show a README and embed live stories, Svelte setup hooks run before the story mounts and can wrap it, and Solid gets Dynamic source.
It is a minor, and it has one breaking change, for Svelte setup files, under its own heading below. Nothing else is renamed or removed, and no version floor moved. A book in any other framework needs no change. These other things behave differently:
@poveste/plugin-solidhas a new peer,vite^8.0.0.povestealready requires the same range, so a Solid book installs nothing new.- A standalone
.story.mdwith only a file likeGuide.story.test.tsbeside it now gets its own page (#1636). Before, that file counted as its story. - On Chrome 118–131 and Safari 17.4–17.x, the Source panel shows code as plain text, not highlighted (#1632, #1634). It's in the fixes below, since a fresh 0.22.1 install on those browsers got no story pages at all.
🚨 Breaking Changes
- A Svelte setup hook now runs before the story mounts, so there is no
app(#234, #1624, #1639, #1640). This covers the setup file'ssetupSvelteand a story's or variant'ssetupApp, in Svelte, SvelteKit and SvelteKit 3 books. Before, a hook ran once the story had rendered, so nothing it set up could reach the story. What a setup file has to change:- A hook that uses
appnow throws, andpoveste buildfails, with a message saying hooks run before the story mounts, and pointing tosetContextandonMount. Nothing replacesapp: it was the mounted component instance, with nothing to register on. To hand a value to the story, use the newsetContext, and read it withgetContextin any component. Destructuringappwithout using it, as the 0.22.1 guide's example does, still works. - A hook that reads the story's rendered DOM now finds nothing, with no error, because the story hasn't rendered yet. Move that into a component in the story, using
onMount. - A hook that only touches the document, such as
document.documentElement.dataset.theme, needs no change. - A hook that throws now stops the story mounting, as it does in Vue, and the error names which hook threw: the setup file's, a variant's
setupAppor a plugin's. - What the hook receives has the details.
- A hook that uses
🚀 Enhancements
- A story's docs can load another markdown file, such as a component's README (#161, #1621). In a Vue story it's
<docs src="./README.md" />. In any framework, a sibling or standalone.story.mdtakessrc: ./README.mdin its frontmatter. The path is relative to the story file, and inpoveste dev, editing the README reloads the docs.- It's written for a README, not a book, so a relative link that isn't a story, such as
./LICENSE, stays as written, andpoveste devwarns. Relative images aren't resolved, and the loaded file's own frontmatter is ignored. - A missing file fails
poveste buildand names it.poveste devshows the message in the docs and picks the file up when it comes back. - The guides for Vue and Svelte have the section.
- It's written for a README, not a book, so a relative link that isn't a story, such as
- Markdown docs can embed a live story (#444, #1623, #1641, #1642, #1643).
<poveste-story id="my-button" variant="primary" />on a line of its own shows that story between the paragraphs, in its own sandbox. It works in a.story.md, a Vue<docs>block and a file loaded throughsrc. Withoutvariantyou get the story's first, and an unknown id says so on the page.- An embed loads when you scroll within 200 px of it, so a page of docs boots no sandbox it doesn't show. That uses
scrollMargin, which is Baseline 2025. An older browser boots an embed once it's visible. - Its frame grows with the story up to 400 px, and a taller story scrolls inside it.
- An embed starts from the story's own state. The panel's controls don't drive it.
- It embeds a story that already exists. Importing a component into the markdown itself is what #444 still asks for. The guides for Vue and Svelte have the section.
- An embed loads when you scroll within 200 px of it, so a page of docs boots no sandbox it doesn't show. That uses
- A Svelte setup file can wrap every story with
addWrapper, as Vue, Solid and React can (#232, #1626). Wrappers nest with the first added outermost. Each getsstory,variantandchildren, and a wrapper'ssetContextreaches the story.setupApphas it too. A story test doesn't run wrappers, as in Vue. The Svelte wrapper guide was a "not supported yet" page and now describes it. - Solid's Source panel has a Dynamic view, which follows the state (#1524, #1635). It prints
<Counter count={10} label="Clicked" onIncrement={…} />, thencount={11}after a click in the story. Solid's JSX leaves no tree to read, so the story file is compiled a second time, only when the Source panel asks. That meansrenderand the story file's module-level code run again with no preview behind them, and a signal or store created inrenderprints from its first value. A story that returns DOM, assolid-js/htmldoes, opens on Static. - React's Dynamic source prints a
Map, aSetand a regular expression as code (#1577, #1631), as innew Map([["a", 1]]),new Set(["a", 1])and/a\/b+/gi, where 0.22 printed…. Solid prints them the same way. A subclass ofMaporSetstill prints as…, becausenew Map(...)would make a different value. - A Svelte component whose props type is imported from a relative file gets controls (#501, #1644).
import type { Props } from './types'thenlet { label }: Props = $props()gave no controls at all. The imported file is read, and editing it alone re-reads the props inpoveste dev. Only one relative import is followed: that file's own imports,extends, utility types such asPickandOmit, and$libor package imports aren't. A prop typed through one of those still gets its control from a default. poveste buildwarns when a Node built-in reaches the browser bundle (#1491, #1630). It names the built-in and each file that imports it, just above the result, and the build still exits 0. Calling one in the book fails, and before, the only sign was Vite's own line hundreds of lines up the log, or none at all withlogLevel: 'error'.poveste devdoesn't print it.
🩹 Fixes
- On Chrome 118–131 and Safari 17.4–17.x, a built book's story pages render again (#1632, #1634). Shiki 4.6.0 calls
Response.prototype.bytes, which those browsers don't have, as its Wasm module loads, and that took the whole story view down. A fresh install of 0.22.1 resolves Shiki 4.6.0, so it's likely affected. Those browsers now get the Source panel in plain text, the rest of the page works, and the console shows one error per story. Highlighting isn't restored there, and the documented browser floor hasn't moved. - A
.story.mdin a subfolder shows its docs on Windows (#1625, #1636). It showed nothing, with no error, in a built book and inpoveste dev, and a standalone page in a subfolder had the same problem. The same PR fixes three things on every platform: deleting a sibling.story.mdno longer leaves its story pointing at it,Tag.story.mdno longer attaches toTag.story-old.story.vue, andpages/tag.story.mdandpages-tag.story.mdno longer show each other's docs. - A
v-forref over components in a Vue story keeps its instances (#1614, #1615). The 0.22.1 notes said this case was still overwritten after mount. It isn't now, whether the ref starts asref([])orref(null). The panel still lists a template ref, asnullor[]. - A config with top-level await that isn't an ES module gets Poveste's message again on Vite 8.3.5 (#1617, #1620). Rolldown 1.2.16 reports it under a new code, so the reader got the bundler's advice to use an output format they can't set. The config still fails, as it should. Only the message changes.
📖 Documentation
- The supported versions table lists the three declared peers it left out (#1619, #1627):
@sveltejs/vite-plugin-svelte^7.3.0,vite-plugin-solid^2.11.0and React DOM^19.0.0. The Svelte page said^7for the first, and now says^7.3.0. - The Nuxt guide says a new project's
ERR_PNPM_IGNORED_BUILDSisn't Poveste failing (#1608, #1611). A freshnuxi initexits 1 onesbuildbefore Poveste is added.pnpm approve-builds esbuildstops it without a prompt.
🚀 Features
- app:
- node:
- react:
- solid:
- svelte:
🐞 Bug Fixes
- app:
- node:
- Keep the top-level await hint on Vite 8.3.5's error code - by @50rayn in #1620 (f0dff)
- Keep story pages working when Shiki's Wasm module throws at load - by @50rayn in #1634 (5920a)
- Show a story's markdown docs on Windows - by @50rayn in #1636 (bdfee)
- Warn when a Node built-in reaches the browser bundle - by @50rayn in #1630 (07cbe)
- svelte:
- vue: