PHPackages                             chrisvasey/sage-storybook - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. chrisvasey/sage-storybook

ActiveLibrary

chrisvasey/sage-storybook
=========================

Storybook integration for Sage WordPress themes using Blade components

04PHPCI passing

Since Sep 6Pushed 8mo agoCompare

[ Source](https://github.com/chrisvasey/sage-storybook)[ Packagist](https://packagist.org/packages/chrisvasey/sage-storybook)[ RSS](/packages/chrisvasey-sage-storybook/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

Sage Storybook
==============

[](#sage-storybook)

[![Tests](https://github.com/chrisvasey/sage-storybook/workflows/Tests/badge.svg)](https://github.com/chrisvasey/sage-storybook/actions)[![Latest Stable Version](https://camo.githubusercontent.com/e0b70f62218e1cdf2c5d228751988e6fd1671696716b247516a38f9bc2e1a096/68747470733a2f2f706f7365722e707567782e6f72672f636872697376617365792f736167652d73746f7279626f6f6b2f762f737461626c65)](https://packagist.org/packages/chrisvasey/sage-storybook)[![Total Downloads](https://camo.githubusercontent.com/521f17fc1eaff22d755466c46816309e7e14800f6a78e53a51aee9e3b582502a/68747470733a2f2f706f7365722e707567782e6f72672f636872697376617365792f736167652d73746f7279626f6f6b2f646f776e6c6f616473)](https://packagist.org/packages/chrisvasey/sage-storybook)[![License](https://camo.githubusercontent.com/939fe78cffbb2e416db37bf886e08be1b8c3cc0e7c1566d860ce916a148f2a07/68747470733a2f2f706f7365722e707567782e6f72672f636872697376617365792f736167652d73746f7279626f6f6b2f6c6963656e7365)](https://packagist.org/packages/chrisvasey/sage-storybook)

A modern Storybook integration for [Roots Sage](https://roots.io/sage/) WordPress themes that allows you to develop, test, and document your Blade components in isolation.

Features
--------

[](#features)

- 🚀 **Server-side rendering** of Blade components via HTTP API
- 🎨 **Theme integration** with your Sage theme's CSS and assets
- 🔧 **Hot reloading** and component introspection
- 📖 **Interactive documentation** with Storybook's full feature set
- ⚡ **Vite integration** for fast development
- 🛡️ **Security-focused** with configurable environment restrictions

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel/Illuminate 10.0+ or 11.0+
- Roots Sage theme with Acorn
- Node.js 18+
- Storybook 8.0+

### WordPress Plugins (for blocks support)

[](#wordpress-plugins-for-blocks-support)

To use Gutenberg blocks in Storybook, you'll need these plugins installed:

- **Advanced Custom Fields Pro** - Core field functionality

    ```
    composer require wpengine/advanced-custom-fields-pro
    ```
- **ACF Composer** - Programmatic field management (recommended)

    ```
    composer require log1x/acf-composer
    ```

These plugins enable the `blocks.*` component prefix in Storybook and allow you to develop and document your custom Gutenberg blocks alongside regular Blade components.

Installation
------------

[](#installation)

### 1. Install the Composer package

[](#1-install-the-composer-package)

```
composer require --dev chrisvasey/sage-storybook
```

### 2. Run the installation command

[](#2-run-the-installation-command)

```
wp acorn storybook:install
```

This will:

- Create the `.storybook/` directory with configuration files
- Update your `package.json` with required dependencies
- Create an example story
- Publish the configuration file

### 3. Configure your site URL

[](#3-configure-your-site-url)

Edit `.storybook/preview.js` and update the configuration:

```
import { configure } from '@storybook/blade-loader';
// Import the theme CSS directly via Vite
import '../resources/css/app.css';

// Configure blade loader for your site
configure({
  apiBaseUrl: 'https://your-site.test', // Your local development URL
});
```

### 4. Build your theme assets

[](#4-build-your-theme-assets)

```
npm run build
```

### 5. Start Storybook

[](#5-start-storybook)

```
npm run storybook
```

Visit `http://localhost:6006` to see your Storybook instance.

Creating Stories
----------------

[](#creating-stories)

Stories are created using Storybook's Component Story Format (CSF). Here's a basic example:

```
// resources/stories/components/Button.stories.js
import { renderBlade } from '@storybook/blade-loader';

export default {
  title: 'Components/Button',
  render: renderBlade,
  parameters: {
    server: {
      component: 'components.button', // Path to your Blade component
    },
  },
  argTypes: {
    text: { control: 'text' },
    variant: { control: 'select', options: ['primary', 'secondary'] },
    disabled: { control: 'boolean' },
  },
  args: {
    text: 'Click me',
    variant: 'primary',
    disabled: false,
  },
};

export const Default = {};

export const Secondary = {
  args: { variant: 'secondary' },
};

export const Disabled = {
  args: { disabled: true },
};
```

### Component Requirements

[](#component-requirements)

For best results, ensure your Blade components:

1. **Use default values for props:**

    ```
    @php
    $text = $text ?? 'Default Text';
    $variant = $variant ?? 'primary';
    @endphp
    ```
2. **Handle slots gracefully:**

    ```

        {{ $slot ?? $text }}

    ```
3. **Are self-contained** (don't rely on WordPress-specific context)

### Working with Gutenberg Blocks

[](#working-with-gutenberg-blocks)

If you're using ACF Composer for Gutenberg blocks, you can document them in Storybook too:

```
// resources/stories/blocks/Title.stories.js
import { renderBlade } from '@storybook/blade-loader';

export default {
  title: 'Blocks/Title',
  render: renderBlade,
  parameters: {
    server: {
      component: 'blocks.title', // Path to your block's Blade template
    },
  },
  argTypes: {
    title: { control: 'text' },
    background_image: { control: 'text' },
    text_colour: { control: 'color' },
  },
  args: {
    title: 'Sample Title',
    background_image: '',
    text_colour: '#000000',
  },
};

export const Default = {};
export const WithBackground = {
  args: {
    background_image: 'https://via.placeholder.com/1200x400',
  },
};
```

**Note:** Blocks require the ACF and ACF Composer packages to be installed and configured in your WordPress site.

Component Organisation
----------------------

[](#component-organisation)

Sage Storybook automatically discovers components in these directories:

- **`resources/views/components/`** - Standard Blade components

    - Stories: `components.button`, `components.card`, etc.
- **`resources/views/blocks/`** - ACF Composer Gutenberg blocks

    - Stories: `blocks.title`, `blocks.hero`, etc.
    - Requires ACF Pro + ACF Composer
- **`resources/views/partials/`** - Theme partials and includes

    - Stories: `partials.header`, `partials.footer`, etc.

You can customise these paths in the configuration file or add additional prefixes as needed.

Configuration
-------------

[](#configuration)

The package can be configured via the published config file `config/storybook.php`:

```