ubook v0.0.34

uBook is a zero configuration Storybook and visual snapshot testing tool for users of Base Web component library. It comes with multiple addons as Accessibility, Actions, Knobs and Links. It also has a special Base Web addon so you can switch between different themes, background colors, breakpoints and right to left direction:

Do you need more addons or change the default theme? The configuration is completely optional but possible and very flexible.

Installation

yarn add ubook

There are also multiple peer dependencies that need to be present in your project (the place where you keep your stories):

{
  "baseui": "^9.50.0",
  "react": "^16.12.0",
  "react-dom": "^16.12.0",
  "styletron-engine-atomic": "^1.0.0",
  "styletron-react": "^5.0.0"
}

You can install them with a single command:

yarn add baseui react react-dom styletron-engine-atomic styletron-react

Start Storybook

npx ubook

CLI Options

-p, --port [number]          [dev] Port to run Storybook. 0 sets a random empty port. (default: 51372)
-x, --host [string]          [dev] Host to run Storybook
--quiet                      Suppress verbose build output
--smoke-test                 [dev] Exit after successful start
--ci                         [dev] CI mode (skip interactive prompts, don't open browser)
-o, --output-dir [dir-name]  [static] Directory where to store built files (enables static mode)
-w, --watch                  [static] Enable watch mode
-V, --version                output the version number
-h, --help                   display help for command

Configuration

By default, ubook assumes that all stories can be found in ./src/**/*.stories.js. Expect an error if there is no src folder in your project.

If you use a different file structure you can modify it by creating ubook.config.js:

module.exports = (config) => ({
  ...config,
  stories: ["stories/**/*.stories.js"],
});

ubook.config.js can be used to configure all aspects of Storybook. It's a superset of .storybook/main.js and aims to make the Storybook's configuration less chaotic and centralized. The list of all config options with default/example values:

{
  stories: ["src/**/*.stories.js"],
  // https://storybook.js.org/docs/configurations/options-parameter/
  options: {
    isFullscreen: false,
    showNav: true,
    showPanel: true,
    panelPosition: "bottom",
    sidebarAnimations: true,
    enableShortcuts: true,
    isToolshown: true,
    theme: {
      brandTitle: "uBook",
      brandUrl: "https://github.com/uber/ubook",
      brandImage: "/ubook-logo.svg",
    },
    selectedPanel: "baseweb/panel",
  },
  // you can add more 3rd party addons
  addons: [
    path.join(__dirname, "../dist/register.js"),
    "@storybook/addon-a11y",
    "@storybook/addon-actions",
    "@storybook/addon-knobs",
    "@storybook/addon-links",
  ],
  base: {
    // feel free to add your custom theme
    themes: [
      { name: "Light Move", value: LightThemeMove, default: true },
      { name: "Dark Move", value: DarkThemeMove, default: false },
      { name: "Light", value: LightTheme, default: false },
      { name: "Dark", value: DarkTheme, default: false },
    ],
    // first we do a lookup in the selected Base theme
    // the value can be also absolute: #F1F1F1 (string)
    backgrounds: [
      { name: "Primary", value: "backgroundPrimary", default: true },
      { name: "Secondary", value: "backgroundSecondary", default: false },
      { name: "Tertiary", value: "backgroundTertiary", default: false },
    ],
    // first we do a lookup in the selected Base theme
    // tthe value can be also absolute: 800 (number)
    breakpoints: [
      { name: "Small", value: "small", default: false },
      { name: "Medium", value: "medium", default: false },
      { name: "Large", value: "large", default: false },
    ],
  },
  // inject additional global styling for all previews
  previewCss: `body { margin: 2em; }`,
  // wrap all stories with a React component
  previewProvider: ({ children }) => (
    <div>
      <h1>Global Title</h1>
      {children}
    </div>
  )
}

Babel

uBook looks for babel.config.js or .babelrc in the current working directory (typically the project root) and then recursively in all parent directories. If no babel config is found, the default one is used.

Base Web Addon

You can set default theme, background, breakpoint or RTL for a specific stories only, example.stories.js:

import React from "react";
import { Button } from "baseui/button";

export default {
  title: "My project",
  parameters: {
    baseweb: {
      theme: "Dark Move",
      background: "Secondary",
      breakpoint: "Medium",
      rtl: true,
    },
  },
};

export const Basic = () => (
  <Button onClick={() => alert("click")}>Button</Button>
);

Visual Snapshot Tests

Visual snapshots are a great way to make sure that your components work and look as expected. ubook-snapshot finds all your stories, opens them in Chrome, Firefox and Safari and saves their screenshots into ./artifacts. A subsequent run compares existing screenshots pixel by pixel and if there is a mismatch, you get an error and ./artifacts/_diff/*.png is created.

npx ubook #storybook server needs to be running first
npx ubook-snapshot

There is no configuration needed but you can always customize through this hierarchy:

1. CLI options
2. ./ubook.config.js (coming, so far stories field is respected)
3. stories parameters ubook - all stories in a file or single story, adapting storybook's addon configuration API (coming)

CLI Options

-u, --update             update mistmatched snapshots
-o, --output [string]    directory to save snapshots (default: "./artifacts")
-s, --stories [string]   search glob for stories (default: "src/**/*.stories.js")
-b, --browsers [string]  browsers used (default: "chromium,webkit,firefox")
--debug                  turn off the headless mode and add 200ms delay to all actions
--meta                   generate meta.json file providing more context for snapshots
--width <number>         viewport width
--height <number>        viewport height
--fullscreen             snapshot full viewport (no auto height)
--scale <number>         device scale (default: 2)
--threshold <number>     0 to 1 sensitivity for pixelmatch (default: 0.1)
--host [string]          host of Storybook server (default: "http://localhost")
--port [number]          port of Storybook server (default: 51372)
-V, --version            output the version number
-h, --help               display help for command

Configuration

ubook-snapshot makes three screenshot (one for each browser) by default with these settings:

theme: "Light Move",
background: "Primary",
width: 1200,
height: 800,
fullscreen: false,

You can change these settings globally through the CLI parameters or per stories/story in your files. For example:

export default {
  title: "Example",
  parameters: {
    baseweb: {
      width: 300,
      fullscreen: true,
    },
  },
};

export const one = () => <button>one</button>;
export const two = () => <button>two</button>;
two.story = {
  parameters: {
    baseweb: {
      height: 500,
    },
  },
};

will result in 3+3 screenshots:

• button one: 300px width (the file level), 800px height (default)
• button two: 300px width (the file level), 500px height (the story level)

Exports

This library is bundling together multiple addons and the main storybook lib:

• @storybook/addon-a11y
• @storybook/addon-actions
• @storybook/addon-knobs
• @storybook/addon-links
• @storybook/react

You can directly export their APIs as:

import { storiesOf } from "@storybook/react";
import { action } from "@storybook/addon-actions";

We also re-export everything from the ubook, so you can do

import { storiesOf } from "ubook";
import { action } from "ubook";

This might be helplful if you are enforcing the ESLint rule no-extraneous-dependencies.