Component Driven Development for Static Deliverables: A Retrospective

Testing variations

Building components in isolation with Storybook also gives us the ability to test multiple implementations and variations of the same component.

Let’s imagine a Media component with the following pug and CSS:

Media.pug:

mixin Media(params={})
  - const props = Object.assign({ image: '', reverse: false }, params)
  .Media(type=props.type, class={ '-reverse': props.reverse })&attributes(attributes)
    img.Media__image(src=props.image)
    .Media__body
      block

.Media {
  display: flex;
}

.Media__image {
  flex: 0 0 auto;
}

.Media.-invert {
  flex-direction: row-invert;
}

To verify how the -invert variant renders, we could create two separate stories.

A more compelling solution is using Storybook Addon Knobs to dynamically tweak our component’s props.

The advantage of this approach is that we can test multiple combinations of modifiers in the same story.

In the following example we use the boolean knob to toggle the value of the reverse prop and, at the same time, we use the select knob to switch between two different images with a totally different aspect ratio.

Media.stories.js:

import { withKnobs, boolean, select } from '@storybook/addon-knobs'

import { renderer } from 'storypug'
import Media from './Media.pug'

const { html } = renderer()

const images = [
  'https://via.placeholder.com/150',
  'https://via.placeholder.com/350x150',
]

export default {
  title: 'Components/Media',
  decorators: [withKnobs],
}

export const Default = () =>
  html(
    Media,
    {
      image: select('Image', images, images[0]),
      reverse: boolean('Reverse Style', false),
    },
    '<p>Contents...</p>',
  )

Here below is how the story will look like in the browser:

Implementing JavaScript interactions

Working with JavaScript in an HTML component-driven project poses some questions related to where and how we should apply interactions.

About the where, we suggest to keep JavaScript on feature components. Rephrasing the definition of organism by the Atomic Design methodology: feature components are groups of components joined together to form a relatively complex, distinct section of an interface. That means that compound components like image galleries, forms and modals are good candidates to hold JavaScript logic, while simple buttons and other primitive components should consist just of HTML and CSS.

As for the how, it really depends on the nature and requirements of your project. Most of the time we use Stimulus, a framework built to simplify and organize a frontend codebase in static or server-side powered projects.

We can map Stimulus controllers to feature components and thus develop them in isolation within Storybook.

As an example, let’s build a search component:

Search.pug:

//- load children components
include /components/Button/Button

mixin Search(props={})
  form.Search(
    action="/search"
    role="search"
    data-controller="search"
    data-action="search#send"
  )
    label.Search__field
      span.Search__label Keywords
      input.Search__input(type="search" name="keywords" data-target="search.keywords")
    +Button({ type: 'submit' }) Search

The controller would look like this:

Search.js:

import { Controller } from 'stimulus'

export default class SearchController extends Controller {
  static targets = ['keywords']

  send(e) {
    e.preventDefault()
    const query = this.keywordsTarget.value.trim()

    if (!query) {
      alert(`Type a keyword!`)
      return
    }
    alert(`Fetching results for: "${query}"...`)

    // fetch search results...
  }
}

To initialize the controller, Stimulus requires us to register it into a container Application class instance. In common scenarios the Stimulus application would be bound to the html element, but in our case we need to create an isolated context for our component. To achieve this we’ll use Storypug’s render helper, which renders the Pug component into a DOM tree within a wrapper element. We’ll then use that wrapper element to initialize a local (isolated) application with the search component as its only child controller.

Search.stories.js:

import { renderer } from 'storypug'
import Search from './Search.pug'
import { Application } from 'stimulus'
import SearchController from './Search'

const { render } = renderer()

export default {
  title: 'Components/Search',
}

export const Default = () => {
  // render instead of returning the raw HTML
  const wrapper = render(Search)

  // initialize a local stimulus application
  const application = Application.start(wrapper.el)

  // register (initialize) the Search controller
  application.register('search', SearchController)

  // return the application wrapper element
  return wrapper.el
}

Here below is a demonstration of the component in action:

Improvements in testing process

An added benefit of working with CDD and Storybook is that it makes it easier to introduce unit testing in your codebase.

While, in general, it’s considered best practices to prefer integration over unit testing for frontend projects, our specific scenario can benefit from a feature originally introduced by the Jest framework called snapshots.

By using snapshots, Jest stores the HTML rendered by our component and then, on subsequent executions, matches the component’s HTML with the stored one. That lets us track inconsistencies and possible errors introduced by changes to the component and to its children. More importantly, it also lets us verify that the component is rendering the expected HTML.

With the latest versions of Storybook using stories for snapshot testing is as immediate as importing them into a test file:

Button.test.js:

import { Default, Submit } from './Button.stories'

describe('Button', () => {
  test('matches the Default snapshot', () => {
    expect(Default()).toMatchSnapshot()
  })
  test('matches the submit snapshot', () => {
    expect(Submit()).toMatchSnapshot()
  })
})

The Storypug documentation includes details on how to configure Jest to use .pug templates in test files.

For your internal team

In fact, even when adopting an agile approach to development, it is sometimes difficult to share your progress within a multi-disciplinary team.

Providing designers and project managers with a navigable, curated preview of your work allows for early feedback and validation.

On small projects, you could create a static build of Storybook and publish it to a private web space to be shared with team members.

On large scale projects, possibly involving multiple developers, you could setup a continuous deployment system that publishes an updated version of the style guide for every branch at each push (a good candidate for this task is Netlify).

Another part of the team that benefits from the CDD approach as described until now, are backend developers. When the frontend and backend template implementation happens at different stages, a backend developer can use Storybook both as a dictionary to browse components and as a benchmark to validate the final, production-ready implementation.

For stakeholders

Another aspect of using CDD and Storybook we have found valuable is that it helps us improve the communication with clients and stakeholders.

Developing a page template, especially in the earlier phases of a project, can be a lengthy process that could leave the stakeholders without any tangible proof of your efforts and progress.

Instead, presenting a style guide like Storybook to stakeholders can convey to them that your team is committed to the project. It is also a good deliverable to outline the kind of effort (in terms of components) needed to create supposedly simple UI patterns like, for example, off-canvas menus.

As a documentation tool

Moreover, with the latest addition of the Docs addon in version 5.2, Storybook can be used as a full-fledged documentation tool.

Besides JavaScript stories, Storybook now supports Markdown and MDX files, allowing both developers and non-developers to write rich documentation for components, design guidelines and integration guides.

With MDX, an extension of Markdown supporting React components, you can also use a set of built-in components to present the project’s typography and color palette in a graphic and intuitive way (see this article for more details).