Packages
StoryShelf is a set of small packages. createShelfApp from @storyshelf/app composes them: a database, storage, an optional capture runner, and optional authentication, notifications, design links and AI. Each package page has its install line, configuration and, under API, the generated TypeScript reference for every export.
| Package | What it does |
|---|---|
@storyshelf/core | Adapter interfaces, models, the capture pipeline, diffing and retention (no HTTP). |
@storyshelf/app | The Hono app: JSON API under /api/v1 and the server-rendered UI. |
@storyshelf/affected | Affected capture: picks the stories a change impacts by tracing the dependency graph. |
@storyshelf/image | Pixel diffs, diff overlays and thumbnails on a worker pool. |
@storyshelf/observability | OpenTelemetry tracing, metrics and log correlation. |
@storyshelf/auth | Local accounts, social login, OIDC, SAML SSO and passkeys. |
@storyshelf/ai | AI insights: build triage and project health. |
@storyshelf/mcp | MCP server that lets AI agents read builds and comment on reviews. |
Databases
Section titled “Databases”| Package | What it does |
|---|---|
@storyshelf/db-sqlite | The default. SQLite, with Turso, better-sqlite3, Bun and D1 presets. |
@storyshelf/db-postgres | Postgres, with Neon, Vercel, pg and PGlite presets. |
@storyshelf/db-mysql | MySQL and MariaDB, with PlanetScale and TiDB presets. |
Storage
Section titled “Storage”| Package | What it does |
|---|---|
@storyshelf/storage-local | The default. Blobs on the local filesystem. |
@storyshelf/storage-s3 | Amazon S3 and compatible stores (R2, MinIO, Spaces). |
@storyshelf/storage-azure | Azure Blob Storage. |
@storyshelf/storage-gcs | Google Cloud Storage. |
Capture runners
Section titled “Capture runners”| Package | What it does |
|---|---|
@storyshelf/runner-playwright | Renders stories with Playwright: Chromium, Firefox and WebKit. |
@storyshelf/runner-puppeteer | Renders with Puppeteer and chrome-headless-shell, for smaller images. |
Design and notifications
Section titled “Design and notifications”| Package | What it does |
|---|---|
@storyshelf/design-figma | Links components to Figma: link checks, metadata and previews. |
@storyshelf/notify-chat | Slack and Microsoft Teams webhook alerts. |
@storyshelf/notify-email | An email transport: SMTP, Mailpit, HTTP APIs. |
@storyshelf/notify-git | GitHub and GitLab commit statuses and pull-request comments. |
Looking for the HTTP endpoints instead? See the HTTP API reference.