Storybook UI Bileşenleri Belgelendirme, modern web geliştirme süreçlerinde önemli bir rol oynar. Bu makalede, Storybook’un temel özelliklerini, kurulumunu ve UI bileşenlerinizi nasıl belgelendirebileceğinizi inceleyeceğiz. Ayrıca, Storybook kullanarak etkili ve kullanıcı dostu belgeler oluşturmak için en iyi uygulamaları paylaşacağız.
Giriş
Storybook, React, Vue, Angular ve diğer popüler frameworkler için kullanabileceğiniz bir UI bileşen geliştirme ve belgeleme aracıdır. Geliştiriciler, tasarımcılar ve proje yöneticileri için bileşenlerinizi izole bir ortamda geliştirmeyi ve test etmeyi kolaylaştırır. Storybook, bileşenlerinizi daha iyi anlamanızı ve yönetmenizi sağlar.
Storybook Nedir?
Storybook, UI bileşenlerinin izole bir ortamda geliştirilmesine, test edilmesine ve belgelenmesine olanak tanıyan açık kaynaklı bir araçtır. Bileşenlerinizin farklı durumlarını ve varyasyonlarını tek bir yerden görebilir ve test edebilirsiniz. Storybook, geliştirme sürecini hızlandırır ve bileşenlerin yeniden kullanılabilirliğini artırır.
Temel Özellikler
- İzole Geliştirme Ortamı: Storybook, bileşenlerinizi uygulamadan bağımsız olarak izole bir ortamda geliştirmenizi sağlar.
- Dokümantasyon ve Belgeleme: Bileşenlerinizin kullanımını ve özelliklerini ayrıntılı olarak belgeleyebilirsiniz.
- Addons: Storybook, ek işlevsellikler eklemek için birçok eklenti (addon) sunar.
- Bileşen Varyasyonları: Farklı durum ve varyasyonlarda bileşenlerinizi test edebilir ve görüntüleyebilirsiniz.
- Yaygın Framework Desteği: React, Vue, Angular, Svelte ve daha birçok framework için destek sunar.
Storybook Kurulumu
Storybook’u proje ortamınıza kurmak oldukça basittir. Aşağıdaki adımları izleyerek hızlı bir şekilde başlayabilirsiniz:
React Projesinde Storybook Kurulumu
npx sb initBu komut, Storybook’u proje ortamınıza ekler ve gerekli yapılandırma dosyalarını oluşturur.
Storybook Kullanımı
Storybook kullanarak bileşenlerinizi belgelemek ve test etmek için temel adımları inceleyelim.
Story Dosyaları Oluşturma
Her bir bileşen için story dosyaları oluşturmanız gerekmektedir. Bu dosyalar, bileşenlerinizin farklı durumlarını ve varyasyonlarını tanımlar.
// Button.stories.js
import React from 'react';
import { Button } from './Button';
export default {
title: 'Example/Button',
component: Button,
};
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',
};Addon Kullanımı
Storybook, bileşenlerinizi daha iyi test edebilmek ve belgeleyebilmek için çeşitli eklentiler sunar. Örneğin, @storybook/addon-actions ve @storybook/addon-links gibi popüler eklentileri kullanabilirsiniz.
npm install @storybook/addon-actions @storybook/addon-linksArdından, .storybook/main.js dosyasına bu eklentileri ekleyin:
module.exports = {
addons: [
'@storybook/addon-actions',
'@storybook/addon-links',
],
};Storybook ile Bileşenlerin Test Edilmesi
Storybook, bileşenlerinizi test etmek için güçlü araçlar sunar. Farklı durum ve varyasyonlarda bileşenlerinizi test edebilir ve görselleştirebilirsiniz.
Farklı Durumlar ve Varyasyonlar
Bileşenlerinizi farklı durumlarda test etmek için story dosyalarında varyasyonlar oluşturabilirsiniz. Örneğin, bir buton bileşenini farklı renk ve boyut seçenekleri ile test edebilirsiniz.
// Button.stories.js
export const Large = Template.bind({});
Large.args = {
size: 'large',
label: 'Button',
};
export const Small = Template.bind({});
Small.args = {
size: 'small',
label: 'Button',
};Aksiyonlar ve Etkileşimler
Bileşenlerinizin kullanıcı etkileşimlerini test etmek için @storybook/addon-actions eklentisini kullanabilirsiniz. Bu eklenti, bileşenlerinizin tıklama, fare hareketi gibi etkileşimlerini izler ve kaydeder.
import { action } from '@storybook/addon-actions';
export const Clickable = Template.bind({});
Clickable.args = {
onClick: action('button-click'),
};Storybook ile Dokümantasyon Oluşturma
Storybook, bileşenlerinizin dokümantasyonunu oluşturmak için güçlü araçlar sunar. Bileşenlerinizi ayrıntılı olarak belgeleyebilir ve kullanım örnekleri sağlayabilirsiniz.
Doc Blocks Kullanımı
Doc Blocks, Storybook’un dokümantasyon araçlarından biridir. Bileşenlerinizi belgelemek ve kullanım örnekleri sağlamak için Doc Blocks kullanabilirsiniz.
import { Meta, Story, ArgsTable } from '@storybook/addon-docs/blocks';
import { Button } from './Button';
<Meta title="Example/Button" component={Button} />
# Button Bileşeni
<Button label="Example Button" />
<ArgsTable of={Button} />Storybook, projelerinizin genel dokümantasyonunu oluşturmak için de kullanılabilir. Proje gereksinimlerini, kullanım kılavuzlarını ve diğer dokümanları Storybook içerisinde barındırabilirsiniz.
Storybook ile En İyi Uygulamalar
Storybook kullanırken dikkat etmeniz gereken bazı en iyi uygulamalar bulunmaktadır. Bu uygulamalar, bileşenlerinizin daha etkili bir şekilde belgelenmesini ve test edilmesini sağlar.
Tutarlı İsimlendirme
Story dosyalarınızda tutarlı bir isimlendirme kuralı kullanmak, bileşenlerinizin daha kolay bulunmasını ve yönetilmesini sağlar.
Ayrıntılı Dokümantasyon
Bileşenlerinizin tüm özelliklerini ve kullanım durumlarını ayrıntılı olarak belgelemek, diğer geliştiricilerin bileşenlerinizi daha iyi anlamasını sağlar.
Düzenli Güncellemeler
Storybook dokümantasyonunuzu düzenli olarak güncellemek, bileşenlerinizin her zaman güncel ve doğru bilgiye sahip olmasını sağlar.
Storybook ile Bileşenleri Belgelendirme Örnekleri
Storybook’u daha iyi anlamak için bazı örnekler üzerinden geçelim. Bu örnekler, Storybook kullanarak bileşenlerinizi nasıl belgeleyebileceğinizi ve test edebileceğinizi gösterecektir.
Button Bileşeni
Bir buton bileşeninin nasıl belgelendirilebileceğini ve farklı varyasyonlarını nasıl oluşturabileceğinizi görelim:
// Button.stories.js
import React from 'react';
import { Button } from './Button';
export default {
title: 'Example/Button',
component: Button,
};
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',
};Input Bileşeni
Bir input bileşeninin farklı durumlarını ve etkileşimlerini nasıl test edebileceğinizi görelim:
// Input.stories.js
import React from 'react';
import { Input } from './Input';
export default {
title: 'Example/Input',
component: Input,
};
const Template = (args) => <Input {...args} />;
export const Default = Template.bind({});
Default.args = {
placeholder: 'Enter text...',
};
export const WithValue = Template.bind({});
WithValue.args = {
value: 'Hello, Storybook!',
};
export const Disabled = Template.bind({});
Disabled.args = {
disabled: true,
placeholder: 'Disabled input',
};Storybook Addons ile Gelişmiş Özellikler
Storybook, bileşenlerinizi daha etkili bir şekilde test edebilmek ve belgeleyebilmek için çeşitli eklentiler sunar. Bu eklentiler, bileşenlerinizin etkileşimlerini izleyebilmenizi, dokümantasyonu geliştirebilmenizi ve daha fazlasını sağlar.
@storybook/addon-actions
Bu eklenti, bileşenlerinizin kullanıcı etkileşimlerini izler ve kaydeder. Örneğin, bir butonun tıklama olayını izlemek için kullanabilirsiniz.
import { action } from '@storybook/addon-actions';
export const Clickable = Template.bind({});
Clickable.args = {
onClick: action('button-click'),
};@storybook/addon-links
Bu eklenti, bileşenler arasında bağlantı kurmanıza olanak tanır. Örneğin, bir bileşenden başka bir bileşene geçiş yapabilirsiniz.
import { linkTo } from '@storybook/addon-links';
export const Primary = () => <Button onClick={linkTo('Button', 'Secondary')}>Go to Secondary</Button>;Storybook ile Görsel Testler
Storybook, bileşenlerinizin görsel testlerini yapmanıza da olanak tanır. Görsel testler, bileşenlerinizin görünümünde beklenmeyen değişiklikler olup olmadığını kontrol eder.
Storybook ile Görsel Testlerin Kurulumu
Görsel testler yapmak için Storybook’un @storybook/addon-storyshots eklentisini kullanabilirsiniz. Bu eklenti, bileşenlerinizin görüntülerini alır ve bunları referans görüntülerle karşılaştırır.
npm install @storybook/addon-storyshots @storybook/addon-storyshots-puppeteer puppeteerGörsel Testlerin Yapılandırılması
Görsel testlerinizi yapılandırmak için bir test dosyası oluşturun ve aşağıdaki kodu ekleyin:
import initStoryshots from '@storybook/addon-storyshots';
import { imageSnapshot } from '@storybook/addon-storyshots-puppeteer';
initStoryshots({
suite: 'Image storyshots',
test: imageSnapshot(),
});Sonuç
Storybook, UI bileşenlerinizi geliştirmenize, test etmenize ve belgelemenize yardımcı olan güçlü bir araçtır. İzole geliştirme ortamı, çeşitli eklentiler ve dokümantasyon araçları ile Storybook, modern web geliştirme süreçlerinde önemli bir rol oynar. Bu rehberde, Storybook’un temel özelliklerini ve bileşenlerinizi nasıl etkili bir şekilde belgeleyebileceğinizi öğrendiniz. Storybook kullanarak projelerinizi daha organize ve kullanıcı dostu hale getirin.
Sıkça Sorulan Sorular
Storybook nedir?
Storybook, UI bileşenlerinin izole bir ortamda geliştirilmesine, test edilmesine ve belgelenmesine olanak tanıyan açık kaynaklı bir araçtır.
Storybook’un avantajları nelerdir?
Storybook, izole geliştirme ortamı, dokümantasyon ve belgeleme araçları, eklentiler ve bileşen varyasyonlarını test etme yetenekleri sunar. Bu, bileşenlerinizi daha iyi anlamanızı ve yönetmenizi sağlar.
Storybook nasıl kurulur?
Storybook’u proje ortamınıza kurmak için npx sb init komutunu kullanabilirsiniz. Bu komut, Storybook’u projeye ekler ve gerekli yapılandırma dosyalarını oluşturur.
Storybook ile hangi frameworkler desteklenir?
Storybook, React, Vue, Angular, Svelte ve daha birçok popüler framework için destek sunar.
Storybook ile nasıl dokümantasyon oluşturulur?
Storybook, bileşenlerinizi ayrıntılı olarak belgelemek için Doc Blocks gibi araçlar sunar. Ayrıca, eklentiler kullanarak bileşenlerinizi daha iyi test edebilir ve dokümantasyon oluşturabilirsiniz.
Kaynaklar
Storybook ile UI bileşenlerinin belgelendirilmesi hakkında daha fazla bilgi edinmek için, bu kaynaklardan yararlanabilir ve projelerinizi daha ileriye taşıyabilirsiniz.
