https://github.com/troychaplin/storybook-starter
https://github.com/troychaplin/storybook-starter
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/troychaplin/storybook-starter
- Owner: troychaplin
- Created: 2026-01-28T15:22:01.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-23T02:34:00.000Z (4 months ago)
- Last Synced: 2026-02-23T07:48:45.510Z (4 months ago)
- Language: TypeScript
- Size: 217 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Storybook Starter for Gutenberg
A starter project for building component libraries that integrate seamlessly with WordPress Gutenberg blocks.
## Features
- **Storybook 10** for component development and documentation
- **Vite** for fast builds
- **TypeScript** for type safety
- **CSS Variables** for easy theming
- **Dual CSS output** - individual files for WordPress, bundled for React/Next.js
## Quick Start
```bash
# Install dependencies
npm install
# Start Storybook development server
npm run dev
# Build the library
npm run build
```
## Project Structure
```
├── .storybook/ # Storybook configuration
├── src/
│ ├── components/ # Component library
│ │ └── Card/
│ │ ├── Card.tsx
│ │ ├── Card.css
│ │ ├── Card.stories.tsx
│ │ └── index.ts
│ ├── styles/
│ │ ├── tokens.css # CSS variables (design tokens)
│ │ └── reset.css # Base styles
│ └── index.ts # Library entry point
├── dist/ # Build output
│ ├── index.js # ES module bundle
│ ├── index.d.ts # TypeScript declarations
│ ├── styles.css # Bundled CSS (all components)
│ └── css/ # Individual CSS files
│ ├── tokens.css
│ ├── reset.css
│ └── Card.css
└── scripts/
└── build-css.js # CSS build script
```
## Customizing the Prefix
All CSS variables use the `--prefix-` prefix (Component UI Library). To customize:
1. Open `src/styles/tokens.css`
2. Find and replace `--prefix-` with your prefix (e.g., `--mylib-`)
3. Update component CSS files with the same replacement
## Usage
### WordPress Blocks (Recommended for WP)
For optimal WordPress performance, load CSS per-component:
**Register styles in PHP:**
```php
// Register tokens globally (in theme or plugin init)
wp_register_style(
'prefix-tokens',
'path/to/your-lib/dist/css/tokens.css',
[],
'1.0.0'
);
// Register component styles with token dependency
wp_register_style(
'prefix-card',
'path/to/your-lib/dist/css/Card.css',
['prefix-tokens'],
'1.0.0'
);
```
**In block.json:**
```json
{
"style": "file:./css/Card.css",
"editorStyle": "file:./css/Card.css"
}
```
**Static block (JS rendered):**
```tsx
// edit.tsx - CSS loaded via block.json, not JS import
import { Card } from 'your-component-library';
export default function Edit({ attributes }) {
return {attributes.content};
}
```
**Dynamic block (PHP rendered):**
```php
function render_card_block($attributes) {
return sprintf(
'
%s
%s
',
esc_html($attributes['title']),
wp_kses_post($attributes['content'])
);
}
```
### React/Next.js
For non-WordPress projects, import the bundled CSS once:
```tsx
// _app.tsx or layout.tsx
import 'your-component-library/styles.css';
// Use components anywhere
import { Card } from 'your-component-library';
function MyPage() {
return (
Card content here
);
}
```
## WordPress theme.json Integration
Map CSS variables to WordPress theme values:
```css
/* In your theme's CSS */
:root {
--prefix-color-primary: var(--wp--preset--color--primary);
--prefix-spacing-md: var(--wp--preset--spacing--40);
--prefix-font-family-base: var(--wp--preset--font-family--body);
}
```
## Scripts
| Command | Description |
|---------|-------------|
| `npm run dev` | Start Storybook development server |
| `npm run build` | Build library for distribution |
| `npm run build:lib` | Build JS/TS only |
| `npm run build:css` | Build CSS files only |
| `npm run build-storybook` | Build static Storybook site |
| `npm run typecheck` | Run TypeScript type checking |
## Adding Components
1. Create a folder: `src/components/ComponentName/`
2. Add files:
- `ComponentName.tsx` - Component implementation
- `ComponentName.css` - Component styles
- `ComponentName.stories.tsx` - Storybook stories
- `index.ts` - Public export
3. Export from `src/index.ts`
## Publishing
1. Update `name` in `package.json` to your package name
2. Update `version` as needed
3. Run `npm run build`
4. Run `npm publish`
## License
MIT