Cách tôi viết document cho react component

754

Chào mấy anh nhé, hôm nay mình chia sẻ việc đơn giản mà mình hay làm khi xây dựng một ứng dụng Reactmà không phải ai cũng chịu khó làm, đó là viết document cho các react component . Hôm nay mình sẽ chia sẽ luôn về các thư viện mà mình thường dùng để làm việc này nhé 😄 .

1. Chuẩn bị

Yêu cầu:

  • Đã có kiến thức cơ bản về reactjs.
  • Đã có kiến thức cơ bản về webpack, babel (nếu bạn muốn custom được các config của một số thư viện cho phép)
  • Môi trường mình sẽ demo:
    • window 10
    • node v12.14.0
    • yarn v1.7.0

Mục đích:

  • Thực hiện để biết cách sử dụng.
  • Khuyến khích thói quen viết document cho những gì mình code.
  • Tự kiểm nghiệm ưu và nhược điểm để sử dụng sao cho phù hợp với từng quy mô dự án.

Những phần bỏ qua:

  • Trong quá trình chúng ta thực hiện thì mình sẽ lượt bớt (không giải thích những thuật ngữ và các lệnh cơ bản).
  • Phần cấu hình mình sẽ không mô tả chi tiết trong bài viết, các bạn có thể theo dõi thông qua repo.
  • .etc

Thư viện

  • Storybook
  • Docz

2 thằng này cốt lõi cũng được xây dựng bằng webpack và babel nên hoàn toàn có thể merge với config của app các bạn nhé.

2. Tiến hành

1. Storybook

Nó là gì ? trang chủ

Storybook is an open source tool for developing UI components in isolation for React, Vue, and Angular. It makes building stunning UIs organized and efficient.

Như mô tả ở trên thì thằng này có thể tích hợp với nhiều thư việc khác không chỉ React. Qúa ngon 😃

Cài đặt các thư viện chính sau

Các file

Sau khi cài các thư viện cần thiết, tiếp theo mình sẽ thêm script trong file package.json để chạy thằng storybook như sau

package.json

Port 6969 anh em chú ý nhé =))

Cấu hình cho storybook

Chúng ta tạo 1 folder tên là .storybook, những file config anh em phang vào đây để storybook chạy nhé. Ở đây mình sẽ thêm 1 file cấu hình sau:

config.js

Mục đích để storybook duyệt qua thư mục ../components và tìm các file có regex tương ứng là /\.stories\.js$/, những file này sẽ được storybook coi là các module mà nó cần load lên UI của nó.

Ngoài ra còn nhiều cấu hình khác anh em tìm hiểu thêm nhé.

Tạo file ví dụ

Tạo một react component trước nhé components/Button/index.js

Đơn giản là tạo các prop để style cho Button component

Storybook component components/Button/index.stories.js

Cách viết cũng khá đơn giản. vì cơ bản nó cũng trả về react component thôi 😄

Chạy

Hiển thị

Nhìn có vẻ xịn 😄

2. Docz

Nó là gì ? trang chủ

It’s never been easier to document your things!

Xây dựng dựa trên 4 nguyên tắc sau:

  1. Zero config and easy to learn.
  2. Blazing fast.
  3. Easy to customize.
  4. MDX based.

Thằng này khá mới, giao diện khi run app được xây dựng bằng gastsby và cũng sịn sò không kém.

Cài đặt các thư viện chính sau

Mình sẽ thêm script trong file package.json để chạy thằng docz như sau

package.json

Cấu hình cho docz

Mình sẽ điều chỉnh một vài cấu hình cho nó, những phần khác nó sẽ dùng cấu hình mặc định của docz. doczrc.js

Thằng docz sẽ duyệt qua các file .mdx thay vì .js hay .jsx nhé.

Tạo file ví dụ

Tạo component components/Button/index.js

Mình vẫn sử dụng component ở ví dụ trên nhưng thêm phần PropTypes cho nó.

File document components/Button/index.mdx

Nhìn có vẻ gọn gàng, chuyên nghiệp nhỉ 😆

Chạy

Hiển thị

Ngon không kém Storybook

3. Kết luận

Đó là những gì mình muốn chia sẽ hôm nay, tuy đơn giản nhưng lại vô cùng sâu sắc, hehe.

Ngoài kia còn rất nhiều thư viện hỗ trợ tạo document cho react component, anh em có thể tìm hiểu thêm nhé.

Cảm ơn mọi người đã đọc bài viết này.

Repo tại đây

TopDev via Viblo

SHARE