Chapter 09
Storybook
Publishing to Pega to check a colour would be like repainting a house to test a swatch. Storybook is the swatch board: a showroom where your component runs on its own, with a pretend Pega standing in.
Pega 24 – 26
Words you will meet
- Storybook
- Mock pConn
The idea
A showroom for components.
StorybookA free tool that shows each component on its own page, in different states, so you can build and test it without the whole application around it. shows one component at a time, in as many situations as you like. Each situation is called a storyOne saved example of a component in a particular state, such as Disabled or Hidden.. It runs on your laptop, reloads the moment you save, and needs no Pega server, no sign-in and no publishing.
The trick that makes this possible is a pretend Pega. Real components ask Pega for their data through a connection object. In Storybook you hand them a small stand-in that answers with sample values. The component cannot tell the difference.
DXCB bundles Storybook out of the box: Constellation 26.1 uses Storybook 9 with Constellation Design System 9, while 25.1 runs on Storybook 8 and 24.2 on Storybook 7. All modern versions leverage interactive Storybook controls with full TypeScript support instead of legacy knobs.
Play
Play with one.
This is a model of the real thing, with the same layout: stories in the sidebar, the component in the middle, controls underneath. Switch story, change a control, and watch the button react. Open the Story code tab to see what each story is made of.
- buttonText
- celebrationText
- disabled
- visibility
Under the hood
How a story is written.
Two small files do it. First, the pretend data:
// mock.ts: pretend Pega data, shared by Storybook and the testsexport const configProps = { buttonText: 'Celebrate', celebrationText: 'Well done!'};Then the stories file. The first half, meta, describes the component once: its sidebar title and the controls. After that, each story is one line that says how it differs from the default.
// demo.stories.tsximport type { Meta, StoryObj } from '@storybook/react-vite'; import { AcmeUICelebrateButton } from './index';import { configProps } from './mock'; // Pega is not here, so hand the component a pretend connection.const mockGetPConnect = () => ({ getValue: () => undefined }); const meta: Meta<typeof AcmeUICelebrateButton> = { title: 'Fields/Celebrate Button', // Category/Name: decides the sidebar position component: AcmeUICelebrateButton, tags: ['autodocs'], // build a documentation page automatically argTypes: { buttonText: { control: 'text', description: 'Text on the button' }, celebrationText: { control: 'text', description: 'Message shown after a click' }, disabled: { control: 'boolean', description: 'Stop the button reacting' }, visibility: { control: 'boolean', description: 'Show or hide the whole component' } }, args: { ...configProps, getPConnect: mockGetPConnect as never }};export default meta; type Story = StoryObj<typeof AcmeUICelebrateButton>; export const Default: Story = {};export const Disabled: Story = { args: { disabled: true } };export const LongText: Story = { args: { buttonText: 'Celebrate this very long label' } };export const Hidden: Story = { args: { visibility: false } };Do it
Start it yourself.
npm run startStorybook # or simply: npm start# opens at http://localhost:6040# if 6040 is busy it quietly picks the next free port above it npm run buildStorybook # builds a static copy (this is what CI builds)Leave it running while you work. Edit index.tsx, save, and the showroom updates in a second or two. It is the fastest feedback loop in the whole process, so most of your time goes here.
A project convention
Getting onto the Home page.
This project's Storybook has a Home page that lists every component automatically. A new component appears there if three things are true:
- It has a
demo.stories.tsxwhose title isCategory/Name, where the category is Templates, Fields, Widgets or Examples. - It has a
config.json. - Its name is in the sidebar order list in
.storybook/preview.tsx.
npm test -- src/docs-home checks all three for you.
Your turn
Questions and comments
Stuck on something, or have a thought? Write it here. To talk about one part, use the Comment button under that section's heading.