Notorious Preying Mantis

    storybook-addon-performance
    TypeScript icon, indicating that this package has built-in type declarations

    0.16.1 • Public • Published

    storybook-addon-performance 🚀

    A storybook addon to help better understand and debug performance for React components

    storybook-addon-performance demo

    🚧 This addon is experimental and a work in progress. We are not on stable versions yet 🚧

    📺 Project overview by Jack Herrington

    Highlights 🌟

    • Zero config (except for interactions): Generate performance information relating to server-side rendering and client-side mounting without any configuration
    • Pin results: You can run some tasks, pin the result, make some changes, rerun the tasks and see what changed
    • Interactions: Add your own custom user interactions to run as a parameter to your story. This lets you time how long interactions take. The API for this is super flexible and powerful!
    • Control: Run all tasks for an overview, or run individual tasks to drill down on specific problems
    • Marked: All tasks are marked with the User Timing API to allow for easy debugging of individual tasks in your browser's performance profiler

    Marking tasks

    Installation

    1. Install storybook-addon-performance
    # yarn
    yarn add storybook-addon-performance --dev
    
    # npm
    npm install storybook-addon-performance --save-dev
    1. Register the addon in .storybook/main.js
    module.exports = {
      addons: ['storybook-addon-performance/register'],
    };
    1. Add the decorator

    You can either add the decorator globally to every story in .storybook/preview.js (recommended)

    import { addDecorator } from '@storybook/react';
    import { withPerformance } from 'storybook-addon-performance';
    
    addDecorator(withPerformance);

    Or you can add it to individual stories:

    Using Component Story Format (CSF)

    import MyComponent from './MyComponent';
    import { withPerformance } from 'storybook-addon-performance';
    
    export default {
      title: 'MyComponent',
      component: MyComponent,
      decorators: [withPerformance],
    };

    Using StoriesOf API

    import MyComponent from './MyComponent';
    import { withPerformance } from 'storybook-addon-performance';
    
    storiesOf('MyComponent', module)
      .addDecorator(withPerformance)
      .add('MyComponent', () => <MyComponent />);

    Usage: Interactions

    Interaction tasks are a task type that can be defined and run on a story-by-story basis. They are useful for timing the interactive performance of your components.

    To define your interaction tasks, first create an array of objects, each containing the name and description (optional) of the task, and a run function that performs whatever tasks you'd like to measure:

    import { InteractionTaskArgs, PublicInteractionTask } from 'storybook-addon-performance';
    import { findByText, fireEvent } from '@testing-library/dom';
    
    // ...
    
    const interactionTasks: PublicInteractionTask[] = [
      {
        name: 'Display dropdown',
        description: 'Open the dropdown and wait for Option 5 to load',
        run: async ({ container }: InteractionTaskArgs): Promise<void> => {
          const element: HTMLElement | null = container.querySelector('.addon__dropdown-indicator');
          invariant(element);
          fireEvent.mouseDown(element);
          await findByText(container, 'Option 5', undefined, { timeout: 20000 });
        },
      },
    ];

    The run function in each task object takes two arguments:

    • container: an HTMLElement container that contains a rendered instance of the story component

    • controls: contains an async timing function that can be optionally called to specify when to start and finish measurements; otherwise the time taken to complete the entire run function is measured. Useful when a task involves some set-up work.

      To use, wrap the operations in question with controls.time as shown below:

      run: async ({ container }: InteractionTaskArgs): Promise<void> => {
        // setup
        await controls.time(async () => {
          // interaction task you'd like to measure
        });
      };

    Note that you can use whatever libraries you'd like to perform these interaction tests – the example above uses @testing-library/dom to open the select in the example and wait for a specific item.

    You can then include the array of interaction tasks inside the performance parameters of your story, with the key interactions:

    // Using the Component Story Format (CSF)
    // https://storybook.js.org/docs/formats/component-story-format/
    import { findByText, fireEvent } from '@testing-library/dom';
    import { PublicInteractionTask } from 'storybook-addon-performance';
    import React from 'react';
    import Select from 'react-select';
    import invariant from 'tiny-invariant';
    
    export default {
      title: 'React select example',
    };
    
    const interactionTasks: PublicInteractionTask[] = [
      {
        name: 'Display dropdown',
        description: 'Open the dropdown and wait for Option 5 to load',
        run: async ({ container }: InteractionTaskArgs): Promise<void> => {
          const element: HTMLElement | null = container.querySelector('.addon__dropdown-indicator');
          invariant(element);
          fireEvent.mouseDown(element);
          await findByText(container, 'Option 5', undefined, { timeout: 20000 });
        },
      },
    ];
    
    select.story = {
      name: 'React select',
      parameters: {
        performance: {
          interactions: interactionTasks,
        },
      },
    };

    Supplied types

    As seen above, the plugin exports two type definitions to assist with creating your own interaction tasks:

    • PublicInteractionTask: defines the object structure for an interaction task; pass an array of these tasks as a parameter to storybook, as shown above.
    • InteractionTaskArgs: the arguments for an interaction task's run function

    Usage: Filtering task groups

    Some components are not designed to work in server side rendering, or on the client. To support this we have created a allowlist that you can optionally pass in to only allow the groups to run that you want to. To configure this option, set the allowedGroups option as part of a story's parameters.

    • Default value: ['server', 'client'] (run everything)
    // Using [Component Story Format (CSF)](https://storybook.js.org/docs/formats/component-story-format/)
    export const onlyClient = () => <p>A story only measuring client-side performance 👩‍💻</p>;
    
    onlyClient.story = {
      parameters: {
        performance: {
          allowedGroups: ['client'],
        },
      },
    };
    
    export const onlyServer = () => <p>A story only measuring server-side performance ‍☁️</p>;
    
    onlyServer.story = {
      parameters: {
        performance: {
          allowedGroups: ['server'],
        },
      },
    };

    Local addon development

    # Start the typescript watcher and a local storybook:
    yarn dev
    
    # Start just the typescript watcher
    # This is needed as storybook does not compile addons
    yarn typescript:watch
    
    # Start the local storybook
    yarn storybook:dev

    Thanks

    Made with ❤️ by your friends at Atlassian


    With ❤️ from Atlassian

    Install

    npm i storybook-addon-performance

    DownloadsWeekly Downloads

    54,914

    Version

    0.16.1

    License

    Apache-2.0

    Unpacked Size

    381 kB

    Total Files

    264

    Last publish

    Collaborators

    • alexreardon
    • darkpurple141
    • harshai
    • andrewcampbell