Yet another CLI to screenshot your Storybook
Clone or download
Latest commit 785d110 Sep 29, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci add ci shell Aug 11, 2018
decl wip Aug 15, 2018
examples feat: add skip option Aug 16, 2018
scripts chore: Add CLI help Aug 12, 2018
src add exit Sep 28, 2018
.gitignore feat: string viewport Aug 12, 2018
.npmignore add ignore file Aug 12, 2018
LICENSE.txt Add readme Aug 11, 2018 chore: bump version Aug 16, 2018
capture.gif Modify readme Aug 15, 2018 rename exaple dir Aug 15, 2018
package.json add exit Sep 28, 2018
register.js create core feat Aug 9, 2018
tsconfig.json refactor, cli opt, and more Aug 11, 2018
tslint.json refactor, cli opt, and more Aug 11, 2018
yarn.lock Add flat/include/exclude options Aug 16, 2018

zisui npm version CircleCI

A fast and simple CLI to screenshot your Storybook.



$ npm install zisui

How to use

zisui runs with 2 modes. One is "simple" and another is "managed".

With the simple mode, you don't need to configure your Storybook. Give an URL, such as:

$ zisui http://localhost:9001

You can launch your server via --serverCmd option.

$ zisui --serverCmd "start-storybook -p 9001" http://localhost:9001

Also, zisui can crawls built and hosted Storybook pages:

$ zisui

Managed mode

If you want to control how stories are captured (timing or size or etc...), use managed mode.

First, you need to register zisui Storybook addon.

/* .storybook/addons.js */

import 'zisui/register';

Next, use withScreenshot decorator to tell how zisui captures your stories.

/* .storybook/config.js */
import { addDecorator } from '@storybook/react';
import { withScreenshot } from 'zisui';


And you can overwrite the global screenshot options by decorating to specific stories.

storiesOf('SomeKind', module)
  viewport: {
    width: 600,
    height: 400,
.add('a story', () => /* your story component */);


Now, the withScreenshot decorator supports React only.

CLI options

usage: zisui [options] storybook_url

  --help                       Show help                                                                       [boolean]
  --version                    Show version number                                                             [boolean]
  --outDir, -o                 Output directory.                                   [string] [default: "__screenshots__"]
  --parallel, -p               Number of browsers to screenshot.                                   [number] [default: 4]
  --flat, -f                   Flatten output filename.                                       [boolean] [default: false]
  --include, -i                Including stories name rule.                                        [array] [default: []]
  --exclude, -e                Excluding stories name rule.                                        [array] [default: []]
  --viewport, -V               Default viewport.                                           [string] [default: "800x600"]
  --disableCssAnimation        Disable CSS animation and transition.                           [boolean] [default: true]
  --silent                                                                                    [boolean] [default: false]
  --verbose                                                                                   [boolean] [default: false]
  --serverCmd                  Command line to launch Storybook server.                           [string] [default: ""]
  --serverTimeout              Timeout [msec] for starting Storybook server.                   [number] [default: 20000]
  --captureTimeout             Timeout [msec] for capture a story.                              [number] [default: 5000]
  --captureMaxRetryCount       Number of count to retry to capture.                                [number] [default: 3]
  --metricsWatchRetryCount     Number of count to retry until browser metrics stable.           [number] [default: 1000]
  --viewportDelay              Delay time [msec] between changing viewport and capturing.        [number] [default: 300]
  --reloadAfterChangeViewport  Whether to reload after viewport changed.                      [boolean] [default: false]

  zisui http://localshot:9009
  zisui http://localshot:9009 -i "some-kind/a-story"
  zisui -e "**/default" -V iPad
  zisui --serverCmd "start-storybook -p 3000" http://localshot:3000


function withScreenshot

withScreenshot(opt?: ScreenShotOptions): Function;

A Storybook decorator to notify zisui to screenshot stories.

type ScreenShotOptions

type ScreenShotOptions = {
  waitImages?: boolean,         // default true
  delay?: number,               // default 0 msec
  waitFor?: string | Function,  // default ""
  viewport?: string | {
    width: number,              // default 800
    height: number,             // default 600
  fullPage?: boolean,           // default true
  skip?: boolean,               // default false
  • viewport: If you set a string parameter, it must be included Puppeteer's device descriptors.
  • waitFor : Sometimes you want control the timing to screenshot. If you set a function to return Promise, zisui waits the promise is resolved. Also you can set global function name to this.
<!-- .storybook/preview-head.html -->
  function myWait() {
    return new Promise(res => setTimeout(res, 5000));
  withScreenshot({ waitFor: 'myWait' }) // wait for 5 seconds.

How it works?

zisui is a crawler using Puppeteer.