תיעוד ושדרוג רכיבים עם storybook

Storybook הוא כלי קוד פתוח פופולרי המשמש לפיתוח, תיעוד ובדיקת רכיבים חזותיים (UI) באפליקציות Web. הוא מאפשר לך לבנות ולראות רכיבים UI בבידוד, בלי צורך להריץ את כל האפליקציה. כמו כן, Storybook התגלה ככלי שמסייע ומייעל גם את צוות הפרודקט , העיצוב , וצוותים נוספים.

היתרונות של שימוש ב-Storybook:

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

Storybook תומך במגוון רחב של פריימוורקים של JavaScript, כולל React, Angular, Vue.js ועוד.=

** חשוב להבין שstorybook הוא כלי פיתוח, אך כן ניתן לפאבלש אותו כמובן.

איך משתמשים ב Storybook:

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

בשביל להתקין storybook כל מה שצריך לעשות זה:

לבחור את הפריימוורק המתאים לכם – לצורך הדוגמה שאציג כאן, נבחר בREACT , הקימו פרויקט נקי של REACT תומך typescript. ואז להריץ את הפקודה:

npx storybook@latest init

לאחר שההתקנה תסתיים, סטוריבוק ירוץ ברקע על פורט 6006 ותוכלו לראות דוגמאות שנדחפו לפרויקט שלכם:

דוגמאות אלו יעזרו לכם להבין קצת איך נראה סטוריז ואת החלוקה בין group stories למשל Button וסטורי בודד שהוא למשל Primary. וכן אפשר לראות גם קובץ Docs שנמצא בתוך Button שגם את זה נייצר בהמשך עבור הרכיבים שלנו. אבל כל הדוגמאות שנדחפו לנו לפרויקט החדש שלנו הן לא באמת משהו שאתם רוצים בפרויקט שלכם, אתם רוצים את הסטוריז שלכם, אז נתחיל בכך שנמחק את כל התיקיה של examples שנדחפה לנו לפרויקט.

עוד רגע לפני שנתחיל, נסתכל על תיקיה .storybook ובה שני קבצי JS (כרגע) main, preview בעלי חשיבות גבוהה ונשתמש בהם בהמשך ההסברים בפוסט זה.

אם נציץ בmain נשים לב שמדובר בקובץ קונפיגורציה, ואפשר לראות דיי בבירור שסטוריבוק מחפש אחר הקבצים בפרויקט שהינם מציינים stories, לפי שורה 3:

/** @type { import('@storybook/react-webpack5').StorybookConfig } */
const config = {
  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/preset-create-react-app",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions"
  ],
  framework: {
    name: "@storybook/react-webpack5",
    options: {
      builder: {
        useSWC: true,
      },
    },
  },
  docs: {
    autodocs: "tag",
  },
  staticDirs: ["..\\public"],
};
export default config;

(בהמשך גם אסביר מהם קבצי mdx)

אני מעדיף לשים את קבצי הstories בתיקיה של כל רכיב, אז לפני שאנחנו יוצרים את קובץ הסוטרי הראשון שלנו, נייצר תחילה קומפוננטה, למשל toast message:

import React from "react";
import style from "./toast.module.scss";

interface ToastProps {
    /**
     * The message to be displayed in the toast
     */
    message: string;
    /**
     * The type to be displayed in the toast
     */
    type: "success" | "error" | "warning" | "info";
}

const Toast: React.FC<ToastProps> = ({ message, type }) => {
    return (
        <div role="alert"
            className={`${style.toastContainer} ${
                type === "success"
                    ? style.bgGreen
                    : type === "error"
                    ? style.bgRed
                    : type === "warning"
                    ? style.bgYellow
                    : style.bgGray
            }`}
        >
            {message}
        </div>
    );
}

export default Toast;

ועכשיו ניצור קובץ נוסף בתיקיה של הרכיב שלנו (בצילום למעלה ניתן לראות איפה נמצא הקובץ)

import type { Meta, StoryObj } from "@storybook/react";
import React from "react";
import Toast from "./Toast";

const meta: Meta<typeof Toast> = {
    title: "Toast",
    component: Toast,
    argTypes: {
    type: {
        control: {
            type: "select",
            options: ["success", "error", "warning", "info"],
        },
    }
    }
};

export default meta;

type Story = StoryObj<typeof meta>;

export const Base: Story = {
    args: {},
};

/** this a Success template of toaster msg */
export const Success: Story = {
    args: {
        message: "Success toast message",
        type: "success",
    },
};

ועכשיו נפרק לחתיכות את מה שעשינו בקובץ הזה ונבין מה זה כל דבר:

Meta

מטה מגדיר את המטה דטה של הסטורי, הוא בסיס כל של הסטורי ויש לו המון הגדרות ואפשרויות, כאן אציג רק חלק מהאפשרויות.
למשל title מגדיר את שם של הstories group , אפשר גם להשתמש בסלש על מנת לייצר תיקיות, למשל אם נרשום בטייטל examples/Toast אז נקבל תצוגה כזו, כך שסטוריז של toast יהיה בתוך examples כך שתוכלו לארגן את הסטוריז שלכם בהתאם לנוחיותכם.

component

ברור לנו שב component נשים את הרכיב שלנו , במקרה הזה הוא Toast – אפשר גם לרנדר את הרכיב עם פונקציה שמחזירה JSX כך תוכלו להגדיר לשלוט במה שתרצו לרנדר.

argTypes

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

decorators

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

הגדרת ה stories

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

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

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

import type { Meta, StoryObj } from "@storybook/react";
import React from "react";
import Toast from "./Toast";

const meta: Meta<typeof Toast> = {
    title: "Toast",
    component: Toast,
    argTypes: {
    type: {
        control: {
            type: "select",
            options: ["success", "error", "warning", "info"],
        },
    },
    },
  tags: ["autodocs"],
    parameters: {
        docs: {
            description: {
                component: "This component do this and that",
            },
        },
    },
};

export default meta;

type Story = StoryObj<typeof meta>;

export const Base: Story = {
    args: {},
};

/** this a Success template of toaster msg */
export const Success: Story = {
    args: {
        message: "Success toast message",
        type: "success",
    },
};

שורה 16 עושה את הקסם ומאפשרת לנו לבנות docs עם storybook וזה נראה כך:

לאחר שתוסיפו את השורה מיד תבחינו שיש לכם קובץ שנקרא Docs בתוך הסטורי גרופ שלכם. ולחיצה עליו תקבלו מבנה של דוקומנטציה מסודרת בה תוכלו לעדכן מידע בעזרת הערות בקוד כפי שמוצג בקובץ Toast.tsx.

ואז אותם הערות תקבלו הישר בתוך הדוקס של הstorybook :

מה עוד אפשר לעשות עם storybook ?

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

פוסטים קשורים:

nextJS – קורס fullstack – רכיבים של nextjs מדריך ריאקט – react hooks | useRef מדריך ריאקט – react hooks | useContext מדריך ריאקט – react hooks | useState