שעת סיפור עם Storybook

מה זה Storybook ולמה זה משמש?

לפי הדוקומנטציה הרשמית, Storybook הינו כלי קוד פתוח (open source) המשמש לבניית קומפוננטות ועמודים בסביבה מבודדת, מהירה ובלתי תלויה. כלומר ללא צורך בהקמת סטאק מורכב (שרת, דאטהבייס וכו׳) וללא תלות בדאטה, מידע שמגיע מ-APIs ועוד. הכלי נחשב בעיני רבים לסטנדרט והינו הספריה הפופולרית ביותר לתיעוד קומפוננטות בצורה ויזואלית, עם 14.16 מיליון הורדות בחודש (!!) ומעל 1400 מפתחים שתרמו קוד (contributors). הספריה מגיעה עם יכולות רבות out-of-the-box וניתן להוסיף יכולות בעזרת תוספים (addons), עליהם ארחיב בהמשך. בנוסף, הספריה תומכת במספר רב של ספריות ופריימוורקים, כגון: ריאקט, ויו (Vue), אנגולר ועוד.

הסיפור מאחורי Storybook

היום זוהי אחת מספריות הקוד הפתוח הפופולריות ביותר, בטח בתחום ה״דוקומנטציה הויזואלית״. אבל תופתעו לגלות, ממש כמוני, שהיא כמעט חדלה מלהתקיים כאשר הפיתוח שלה הופסק לזמן קצר.

על מנת להבין את הדרך שעבר הכלי, בואו נתחיל עם קצת היסטוריה:

1. סטוריבוק 1.0 פותח על ידי חברת סטארטאפ בשם Kadira ושוחרר באפריל 2016.
2. סטוריבוק 2.0 פותח גם כן על ידי Kadira ושוחרר בספטמבר 2016.
3. בדצמבר 2016, Kadira נסגרה והעבודה על סטוריבוק הופסקה לחלוטין באמצע ינואר 2017.
4. באפריל 2017 קמה צעקה ברחבי גיטהאב והכלי עבר לפיתוח, ניהול ותחזוקה של קהילת האופן סורס.
5. סטוריבוק 3.0 שוחרר במאי 2017, בהובלת הקהילה.
6. הגירסה האחרונה ששוחררה היא 6.4 (נכון לכתיבת שורות אלה). כיום סטוריבוק מתוחזק באופן מלא על ידי הקהילה. חלקם גם עומדים מאחורי Chromatic אשר עוסקת בפיתוח כלים למפתחי פרונטאנד ומפתחת בעצמה תוספים לסטוריבוק.

בתחילה, הייתה תמיכה אך ורק בריאקט, אך עם הזמן, התווספו פריימוורקים וספריות נוספות, כאמור.

הכלי זכה לאהדה ושימוש נרחב כבר מהרגע הראשון, בזכות הקלות שניתן היה להוסיף אותו לפרויקטים, תוספות תכופות של פיצ׳רים חדשים ושיווק טוב של Kadira.

כבר במהלך 2016, הוא זכה לתמיכה בתוספים (Addons) אשר פותחו על ידי Kadira בעצמה או על ידי הקהילה, וכן לתמיכה בריאקט נייטיב.

מי שאחראי, בין היתר, על ה״תחייה מחדש״ של סטוריבוק הוא אחד מהאנשים המוכרים ביותר בקהילת הפיתוח בכלל ובקהילה של ריאקט בפרט – דן אברמוב (מהיוצרים של Redux, React Hooks ועוד), שהיה בעצמו תומך נלהב.

לאחר שנפתח issue בגיטהאב, בו נשאל האם הפרויקט ״מת״, דן הציע להעביר את הניהול עליו לקהילה ואף צייץ על כך בטוויטר.

Great to see new maintenance effort in Storybook. This is how open source should work. https://t.co/84XnvsImKs

— дэн (@dan_abramov) March 29, 2017

הוספת Storybook לפרויקט

מהרגע הראשון, אחד היתרונות המובהקים היה ונותר הפשטות והקלות בהן ניתן להוסיף את הכלי לפרויקט. כמה פשוט?

על מנת להוסיפו לפרויקט, כל שעליכם לעשות זה להריץ את הפקודה: npx sb init.

שימו לב – לא ניתן להוסיף את סטוריבוק לפרויקט ״ריק״, כלומר לפרויקט שלא נבחר לו פריימוורק.

הרצת הפקודה תגרום לשינויים הבאים בפרויקט שלכם:

• התקנת הספריות (dependencies) הרלוונטיות
• הוספת סקריפטים לבנייה והרצה של סטוריבוק ב-package.json
• יצירת הקונפיגורציה הדיפולטית תחת התיקייה storybook.
• יצירת כמה ״סיפורים״ לדוגמה

לאחר ההתקנה הראשונית, מומלץ להריץ את הפקודה: npm run storybook על מנת לוודא שההתקנה בוצעה בהצלחה. הרצת פקודה זו תתחיל את סטוריבוק ותשלח אתכם לטאב חדש בדפדפן שלכם, בו תתקבלו על ידי המסך הראשי של הכלי:

במסך זה תמצאו גם לינקים נוספים אשר יעזרו לכם ללמוד על היכולות הנוספות שיש לכלי.

תוספים (Addons) ושימושים נוספים

אישית, אני חושב שזה ה-דבר שהופך את סטוריבוק לכל כך פופולרי ומוצלח.

תוספים אלה הם ספריות קוד פתוח אשר ניתן להתקין בפרויקט שלכם. אלה מרחיבים את יכולותיו ומאפשרים למשתמש לעשות שימושים רבים ומגוונים בכלי.

כיום נתמכים שורה ארוכה של תוספים שפותחו על ידי הקהילה. גם אתם יכולים לפתח תוסף לסטוריבוק ולהשתמש בו בעצמכם או להוציא אותו לקוד פתוח ולשתף עם הקהילה.

ישנם מספר תוספים אשר מגיעים out-of-the-box עם ההתקנה, במידה והתקנתם את הכלי כפי שהסברתי בחלק הקודם, או שאפשר פשוט להתקין אותם ידנית בעזרת הפקודה: npm install -D @storybook/addon-essentials

בין היתר, תוכלו למצוא שם את:

• Docs – תוסף המאפשר להציג עמוד דוקומנטציה לקומפוננטות. את הדוקומנטציה עצמה מוסיפים בעזרת הערות בקוד (JSDoc). בעזרת התוסף, סטוריבוק יודע להמיר את ההערות האלה למסמך ולהציגן בממשק ויזואלי.
• Controls – תוסף זה מוסיף ממשק גרפי לעמוד ומאפשר לשנות את הערכים אותם אנחנו מעבירים לקומפוננטה (לדוגמא, props בריאקט) בלייב.
• Interactions – התוסף מאפשר לכם להפוך סיפורים לאינטראקטיביים (!). כאשר יש צורך לבצע  איזושהי אינטראקציה על מנת להגיע לסטייט מסוים של הקומפוננטה, כמו למשל פתיחה וסגירה של דיאלוג או מילוי פרטים בטופס על מנת לבצע עליהם ולידציה, בעזרת התוסף נוכל לעשות אוטומציה לתהליך הזה. כל שעליכם לעשות הוא לממש את הפונקציה `play` ובה להגדיר את האינטראקציות הנדרשות. הפונקציה ״תתנגן״ אוטומטית לאחר רינדור הקומפוננטה. (תוסף זה עושה שימוש בתוסף אחר של סטוריבוק testing-library, אשר מבוסס על react-testing-library של Kent C. Dodds).

זוהי רק רשימה חלקית של התוספים בהם ניתן להשתמש.

אתם מוזמנים להתרשם מהקטלוג אשר מציג לראווה את שאר התוספים בחלוקה לקטגוריות, כמו: קוד, בדיקות, סטייל, סדר וארגון ועוד.

סיפור לדוגמה

import React from 'react';

import { Button } from './Button';

export default {
  title: 'Example/Button',
  component: Button,
  argTypes: {
    backgroundColor: { control: 'color' },
  },
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Button',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Button',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Button',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Button',
};

דוגמה לקובץ stories עבור קומפוננטת Button מעל ריאקט.

מידע נוסף לגבי הקוד תוכלו למצוא באתר.

לסיכום

אני מאוד מאוד אוהב את הכלי הזה ואת השימושים הרבים שניתן לעשות בו. העובדה שכל כך פשוט להוסיף אותו לפרויקט שלכם ולהרחיב את היכולות שלו לצרכים שלכם, הופכים אותו למוצר צריכה בסיסי לכל מערכת UI.

אני מזמין אתכם לקרוא את הדוקומנטציה המעולה שלהם, הכוללת דוגמאות קוד ועזרים ויזואליים.

אני מבטיח לכם שגם אתם, כמוני, תתאהבו ותתחילו לספר סיפורים לחברים שלכם בצוות.

מוזמנים לפנות אלי לכל שאלה או תגובה