Astrobook

If a story's named export matches the module's filename (e.g., Button.stories.ts exporting const Button = {}), Astrobook will automatically hoist that story to replace the parent component in the UI. This prevents redundant nesting in the sidebar (e.g., showing Button instead of Button/Button).

// Button.stories.ts
import { Button as ButtonComponent } from './Button.tsx'

export default {
  component: ButtonComponent,
}

// Single named export matching module name
export const Button = {}

Decorators are objects used to wrap a component with additional logic or styling. A decorator must have a component (the wrapper) and can optionally take props. The wrapper component must include a slot to render the children.

Note: Decorators are rendered into HTML by Astro and sent to the client. They currently support styling changes but cannot change component context or client-side behaviors.

// Button.stories.tsx
import RedBorderDecorator from './AstroRedBorderDecorator.astro'
import { Button, type ButtonProps } from './Button.tsx'
import { GreenBorderDecorator } from './ReactGreenBorderDecorator.tsx'

export default {
  component: Button,
}

export const PrimaryButton = {
  args: { variant: 'primary' } satisfies ButtonProps,
  decorators: [
    { component: GreenBorderDecorator, props: { width: 10 } },
    { component: RedBorderDecorator },
  ],
}

To prevent Astrobook from being included in your production build, use process.env.NODE_ENV to conditionally add the integration in your astro.config.mjs. This is ideal for adding Astrobook to an existing Astro project without affecting the production site.

// astro.config.mjs
import { defineConfig } from 'astro/config'
import astrobook from 'astrobook'

// https://astro.build/config
export default defineConfig({
  integrations: [
    // On development, Astrobook is available at http://localhost:4321/astrobook.
    // On production, Astrobook is not included.
    process.env.NODE_ENV === 'development'
      ? astrobook({ subpath: '/astrobook' })
      : null,
  ],
})

Astrobook scans for files matching *.stories.{ts,tsx,js,jsx,mts,mjs}. It supports a subset of Storybook's Component Story Format v3, specifically args and decorators. Each file must have a default export (the component metadata) and one or more named exports (the stories).

// src/components/Button.stories.ts
import { Button, type ButtonProps } from './Button.tsx'

export default {
  component: Button,
}

export const PrimaryButton = {
  args: { variant: 'primary' } satisfies ButtonProps,
}

export const SecondaryButton = {
  args: { variant: 'secondary' } satisfies ButtonProps,
}

To replace the default Astrobook landing page with your own custom component, you can provide a custom component to the Astrobook configuration. This allows you to design a unique entry point for your component library documentation.

/* Note: This example demonstrates the pattern of providing a custom component for the home page in the Astrobook configuration. */

Astrobook is a minimal UI component playground for frameworks like React, Vue, Preact, Svelte, Solid, Lit, and Astro. To set it up in a new project:

1. Install dependencies:

   npm install astro @astrojs/react astrobook

2. Configure Astro: Add astrobook to your integrations array in astro.config.mjs.
3. Add scripts to package.json (dev, build, preview).
4. Update .gitignore to exclude dist/ and .astro/.
5. Write stories in .stories.{ts,tsx,js,jsx,mts,mjs} files using a default export for the component and named exports for individual stories.
6. Run the dev server:

   npm run dev

   View your stories at http://localhost:4321.

Astrobook optimizes the navigation tree by hoisting stories when a module acts as a simple wrapper for a single story.

Using the isSingleStory logic, a module is considered a candidate for hoisting if:

1. It contains exactly one story (module.stories.length === 1).
2. The name of that single story matches the name of the module (module.stories[0].name === module.name).

When this condition is met, the StoryNode is added directly to the parent directory's children array, skipping the creation of a ModuleNode level. This results in a flatter, cleaner navigation structure.

export function isSingleStory(module: StoryModule): boolean {
  return module.stories.length === 1 && module.stories[0].name === module.name
}

The sidebar search uses sessionStorage to persist the search state across page navigations. This ensures that if a user searches for something and clicks a link, the search panel remains open and the query is preserved.

Storage Keys:

• astrobook-sidebar-search-open: Set to '1' if the search panel is open.
• astrobook-sidebar-search-query: Stores the current search string.

Search Logic: Search is implemented using CSS filtering. The script injects a <style> element with the ID astrobook-search-style that contains rules to hide tree items ([data-search-text]) that do not match the search terms.