Skip to main content

Documentation

This documentation contains the practices we are using in our React applications during development.

JSDocs​

Storybook​

Explanation from Chat GPT​

Storybook is an open-source tool for building user interfaces and components in isolation, primarily used in the context of developing applications with React. It's designed to help developers create, organize, and showcase individual UI components in a consistent and interactive way. Storybook is particularly valuable for building and maintaining design systems, libraries of UI components, or any project where visual consistency and component reusability are crucial.

Here's how Storybook works and its key features with respect to React:

Isolated Development: Storybook allows you to develop and view individual components in isolation. You can work on a single component independently, which makes it easier to focus on its behavior and design without being distracted by the rest of your application.

Component Showcase: With Storybook, you can create a visual documentation for your components, providing examples of how they can be used. This documentation is typically generated as a gallery with stories for each component.

Interactive Testing: You can interact with components in an isolated environment. You can pass different props, states, or even simulate different scenarios to see how your components behave under various conditions.

Addons: Storybook supports a wide range of addons that enhance its capabilities. These addons can provide features like source code examples, accessibility checks, viewport resizer, and more, making it a powerful tool for development and testing.

Integration with React: Storybook is well-suited for React development. It's easy to set up and integrate with React components. You can write your components in JSX and use them within Storybook stories.

Extensibility: You can customize and extend Storybook to fit the specific needs of your project. This includes adding custom themes, styles, and even creating your own addons.

Collaboration: Storybook promotes collaboration among team members, designers, and other stakeholders by providing a common platform to view and discuss UI components and their behavior.

In a typical workflow, developers write "stories" for each component. A story is a scenario or use case for the component, showcasing its various states and interactions. These stories are organized into a directory structure that resembles your component hierarchy.

To get started with Storybook in a React project, you can use tools like @storybook/react and follow the documentation and guides provided on the official Storybook website. It's a valuable tool for creating and maintaining a library of reusable React components while ensuring consistency and quality in your UI.

How to use Storybook​

  1. First, make sure you have Node.js and npm installed.
  2. Create a new React app using Create React App (CRA) or any other method you prefer.
  3. Install Storybook for React:
npx -p @storybook/cli sb init

This command will initialize Storybook in your project. 4. After initialization, you'll see a .storybook directory in your project, which contains the Storybook configuration files. You can modify the configuration to suit your needs. 5. Create a new directory for your components, for example, src/components. Inside this directory, create a Button.js file for your button component:

// src/components/Button.js
import React from 'react';

function Button({ label }) {
  return <button>{label}</button>;
}

export default Button;
  1. Now, create a story for the button in a Button.stories.js file:
// src/components/Button.stories.js
import React from 'react';
import Button from './Button';

export default {
  title: 'Button',
  component: Button,
};

// Create a default button story
export const Default = () => <Button label="Click me" />;

// You can add more stories for different button states and interactions
export const Disabled = () => <Button label="Disabled" disabled />;
  1. Start Storybook:
npm run storybook

This will start a local development server for Storybook. 8. Open your web browser and go to localhost. You will see your button component showcased with the stories you've defined. 9. You can interact with the component and see how it behaves in different scenarios. 10. Storybook allows you to add more stories for various component variations and states.

Current Implementation of Storybook​

  • Although a well-commented code works for most developers, a tool that can help isolate components and pages to play with as we do in a sandbox can help in better understanding and usability. That's where Storybook comes into picture!
  • In their own words, Storybook is a frontend workshop for building UI components and pages in isolation. For more details, refer to the official documentation here.
  • One of the main reasons to choose this is that it can scrape comments written in JSDocs format in the compoennets and display it in the autodocs generated for each component.
  • We have tried implementing Storybook on SWMM and paused working on it at the moment. One of the reasons is although we are able to host components, we seem to have difficulty housing pages in storybook due to errors, of which below is a common occurrence.
    Uncaught TypeError: Cannot read properties of undefined (reading 'add')
    at r.init (index.module.js:1:1)
    at r.render (index.module.js:1:1)
    at finishClassComponent (react-dom.development.js:17485:1)
    at updateClassComponent (react-dom.development.js:17435:1)
    at beginWork (react-dom.development.js:19073:1)
    at HTMLUnknownElement.callCallback (react-dom.development.js:3945:1)
    at Object.invokeGuardedCallbackDev (react-dom.development.js:3994:1)
    at invokeGuardedCallback (react-dom.development.js:4056:1)
    at beginWork$1 (react-dom.development.js:23964:1)
    at performUnitOfWork (react-dom.development.js:22776:1)
  • The implementation of Storybook is thus been moved to a branch called storybook-dev and is available in SWMM repository.
Note
  • This issue is still present when using 3.5.2 which is the current version.
Note
  • We have previously also tried Docz but discarded the idea due to the errors and unsupported dependencies.