Tworzenie dokumentacji komponentów w Storybook

Dokumentacje komponentów UI stają się standardem w pracy front-end dewelopera. W artykule przedstawiam jak stworzyć dokumentację za pomocą Storybooka.

Czym jest Storybook?

Zgodnie z opisem w dokumentacji Storybook to kolekcja „opowieści” (stories – po angielsku brzmi lepiej ;). Prościej mówiąc każdy stories to komponent, a Storybook pomaga w grupowaniu i wyświetlaniu ich.

Storybook pomaga w tworzeniu Style Guide (o tym terminie pojawi się więcej w innym artykule, zachęcam do googlowania).

Jak korzystać ze Storybooka? Poradnik

Instalacja

W artykule przedstawiam szybki sposób, dzięki CLI.

npx -p @storybook/cli sb init --type html

Parametr type oznacza jakiego typu to będzie projekt – może to być react czy angular. W tym przypadku będzie to HTML.

Więcej na ten temat oraz listę dostępnych opcji można znaleźć w oficjalnej dokumentacji Storybooka. Znajduje się tam również instrukcja Slow Start Guide, która pokazuje jak zainstalować Storybooka krok po kroku (jest tam m.in. dodanie pakietu do package.json czy dodanie pliku konfiguracyjnego).

Uruchomienie Storybooka

Odpowiedzialna za to jest komenda:

npm run storybook

To wszystko!

Tak przedstawia się pierwszy widok po uruchomieniu Storybooka.

Można już zacząć pracę i tworzyć własną dokumentację komponentów.

Tworzenie Storiesa

Dodawanie storiesa jest możliwe na trzy sposoby:

• CSF (Component Story Format) – domyślnie (wykorzystam ten sposób)
• storiesOf API
• MDX syntax – w trakcie tworzenia (w momencie powstawania artykułu)

Przykładowy stories wygląda następująco:

export default {
  title: 'Components|Button',
};

export const heading = () => '<h1>Heading 1</h1>';

export const button = () => {
  const btn = document.createElement('button');
  btn.type = 'button';
  btn.innerText = 'Hello Button';
  btn.addEventListener('click', e => console.log(e));
  return btn;
};

Domyślny export definiuje tytuł komponentu. Natomiast zwykłe exporty to komponenty bądź ich stany (podstrona w Storybooku).

Wszystko jest w plikach .js co oznacza, że nie można korzystać ze zwykłego HTMLa. No chyba, że to React i JSX :).

Hierarchia storiesów

Teraz warto wiedzieć jak budować hierarchię w Storybooku.

W domyślnym eksporcie w parametrze title definiujemy hierarchię.

export default {
  title: 'Components|Button/Nested',
};

Znakiem „|” oddzielamy tytuł najwyższego poziomu, a z pomocą „/” definiujemy jak komponent ma być zagnieżdżony. W powyższym przykładzie „Components” to tytuł sekcji, natomiast „Button” i „Nested” to grupa.

Dodawanie plików CSS, SASS do Storybooka

Domyślnie Storybook pokaże błąd, jeśli zostanie zaimportowany plik CSS czy SCSS. Aby była możliwość korzystania z tego należy odpowiednio skonfigurować Storybooka.

W katalogu .storybook należy utworzyć plik webpack.config.js, w którym należy umieścić poniższy kod.

const path = require('path');
// Export a function. Accept the base config as the only param.
module.exports = async ({ config, mode }) => {
  // `mode` has a value of 'DEVELOPMENT' or 'PRODUCTION'
  // You can change the configuration based on that.
  // 'PRODUCTION' is used when building the static version of storybook.
  // Make whatever fine-grained changes you need
  config.module.rules.push({
    test: /\.scss$/,
    use: ['style-loader', 'css-loader', 'sass-loader'],
    include: path.resolve(__dirname, '../'),
  });
  // Return the altered config
  return config;
};

Powyższy kod dodaje możliwość wczytania plików SCSS w projekcie. Ten kawałek kodu pochodzi z oficjalnej dokumentacji.

No i należy zainstalować zależności.

npm install node-sass sass-loader css-loader style-loader

Teraz wystarczy zrobić import pliku np.:

import './src/_buttons.scss';

Gotowe!

Do dzieła! Podsumowanie

Inspiracją do tego artykułu była chęć stworzenia własnych komponentów, które mogę wykorzystywać wielokrotnie. Idealnym narzędziem wydaje się być Storybook. Jeśli tworzysz wiele projektów to z pewnością zauważasz, że wielokrotnie tworzysz te same komponenty – warto w tej sytuacji stworzyć coś raz i później wielokrotnie wykorzystać.

Pochwal się własną dokumentacją w komentarzu!

Materiały

Oficjalna strona Storybooka – https://storybook.js.org
Dokumentacja – https://storybook.js.org/docs/basics/introduction/