What is @storybook/core-client?
The @storybook/core-client npm package is a part of the Storybook ecosystem, which is an open-source tool for developing UI components in isolation for React, Vue, Angular, and more. It provides the core functionalities required to run and manage the Storybook client, including rendering stories, managing the UI and state, and integrating with the Storybook ecosystem.
What are @storybook/core-client's main functionalities?
Rendering Stories
This feature allows developers to write stories that represent different states of UI components. The code sample shows how to use the Storybook API to define stories for a 'Button' component with different content.
import { storiesOf } from '@storybook/react';
storiesOf('Button', module)
.add('with text', () => <button>Hello Button</button>)
.add('with emoji', () => <button>😀 😎 👍 💯</button>);
Managing UI State
This feature allows addons to interact with the Storybook UI and react to events such as when a story changes. The code sample demonstrates how to register an addon that listens for the STORY_CHANGED event.
import { addons } from '@storybook/addons';
import { STORY_CHANGED } from '@storybook/core-events';
addons.register('my-addon', (api) => {
api.on(STORY_CHANGED, (storyId) => {
console.log('Current story is', storyId);
});
});
Integrating with Storybook Ecosystem
This feature enables the integration of various Storybook addons to enhance the development experience. The code sample shows how to add the 'withKnobs' decorator from the '@storybook/addon-knobs' package to enable dynamic properties for components.
import { addDecorator } from '@storybook/react';
import { withKnobs } from '@storybook/addon-knobs';
addDecorator(withKnobs);
Other packages similar to @storybook/core-client
react-cosmos
React Cosmos is a development tool for creating reusable React components. It allows developers to render components with different props and states, similar to Storybook. However, it focuses more on the component's environment and less on the storytelling aspect.
docz
Docz leverages MDX to allow developers to write documentation alongside their code. It is similar to Storybook in that it provides a way to showcase components, but it focuses more on documentation and less on the isolated development environment.
Storybook Core-Client
This package contains browser-side functionality shared amongst all the frameworks (React, RN, Vue, Ember, Angular, etc).
Preview
The files in src/preview
alongside the @storybook/client-api
package form the "API" of the preview (iframe) side of Storybook. Here is a brief overview of the architecture:
Each framework (e.g. @storybook/react
/ @storybook/angular
/ et al.) initializes the preview by calling into src/preview/start.ts
, passing a render
function that will be used to render stories.
The start
module initializes all the submodules:
StoryStore
(from @storybook/client-api
) - stores the stories and their state as well as the current selection or error.ClientApi
(from @storybook/client-api
) - provides the entry point for storiesOf()
API calls; re-exported by each framework.ConfigApi
(from @storybook/client-api
) - provides the configure API (wrapped by loadCsf
below).StoryRenderer
- controls the HTML that is rendered in the preview (calling the render
function with the current story at appropriate times).url.js
- controls the URL in the preview and sets the selection based on it.loadCsf
- loads CSF files from require.context()
calls and uses ClientApi
to load them into the store.
Each module uses the channel to communicate with each other and the manager. Each module also has direct access to the story store.
Events on startup
The store can only be changed during "configuration". The ConfigApi
will call store.startConfiguration()
, then the user code (or loadCsf
's loader) which will use client API to load up stories. At the end of the user's code the ConfigApi
will call store.finishConfiguration()
. At this point the SET_STORIES
event is emitted and the stories are transmitted to the manager.
The URL of the preview is a "selection specifier" that controls the initial selection, which is chosen when configuration ends. Also (outside of configuration) the SET_CURRENT_STORY
"command" event can be used to set the selection on the store. When the selection is set, a CURRENT_STORY_WAS_SET
event is emitted which triggers a rendering.