js-library-boilerplate: Khởi động dự án JS library trong 5 phút

Mỗi lần bắt đầu viết một JS library mới, mình đều phải ngồi config lại Webpack, Babel, setup UMD exports, lo hot reloading, rồi còn phải nghĩ xem cấu trúc thư mục nên để như thế nào. Mất cả buổi sáng chỉ để có một cái skeleton chạy được. Đến lần thứ ba mình làm cái việc đó, mình mới nghĩ chắc có ai đó đã giải quyết vấn đề này rồi.

Và đúng là có js-library-boilerplate của DevUnltd (fork từ bản gốc của hodgef) là một trong những template đáng dùng nhất mình từng thấy cho use case này.

Nó giải quyết bài toán gì?

Nếu bạn đang viết một React component library, một utility lib, hay bất kỳ thứ gì định publish lên npm bạn sẽ cần:

• Webpack để bundle
• Babel để transpile ES6+ xuống cho compatible
• UMD format để lib của bạn chạy được cả trong Node, browser, và AMD loader
• Hot reloading để dev không phải F5 tay
• SASS/SCSS support nếu lib có CSS
• Jest để viết unit test
• Một cái demo page để showcase

Thay vì tự mày mò từng thứ, boilerplate này gói hết vào một chỗ, đã config sẵn, chạy được ngay.

Nhìn vào cấu trúc thực tế

Sau khi clone về và npm install, bạn sẽ thấy cấu trúc kiểu này:

1├── bin/          # postinstall script
2├── build/        # output sau khi build
3├── config/       # webpack configs
4├── demo/         # demo app để test lib
5├── public/       # static assets cho demo
6├── scripts/      # build/start scripts
7├── src/          # source code của lib
8├── .env
9├── package.json

Cái mình thích là nó tách biệt rõ ràng giữa source của lib (src/) và demo app (demo/). Nhiều boilerplate khác gộp chung lại, dẫn đến lúc build bị lẫn lộn. Ở đây bạn code lib trong src/, còn demo/ là nơi bạn import lib của mình vào để test thử giống hệt cách người dùng thực tế sẽ dùng nó.

Tech stack bên trong

Một điểm đáng chú ý: boilerplate này based on Create React App v5, nghĩa là nó support cả việc build Vanilla JS lib lẫn React lib. Bạn không bị lock vào React, nhưng nếu cần thì infrastructure đã sẵn.

Workflow thực tế khi dùng

Getting started chỉ cần ba bước:

1git clone https://github.com/DevUnltd/js-library-boilerplate.git myLibrary
2cd myLibrary
3npm install

Sau đó:

1npm start       # dev mode với hot reloading
2npm run demo    # build demo page để deploy/showcase
3npm publish     # publish lên npm

Trước khi publish, có một vài thứ cần customize:

1. ./config/webpack.config.js đổi "MyLibrary" thành tên export của lib bạn. Cái này quan trọng vì nó ảnh hưởng đến cách người dùng import qua CDN (window.MyLibrary).
2. package.json điền đầy đủ thông tin, vì metadata này sẽ được dùng để generate file headers trong build output.
3. ./bin/postinstall optional, nhưng nếu bạn muốn hiển thị message gì đó khi người dùng npm install lib của bạn thì config ở đây.
4. LICENSE đừng quên đổi tên tác giả.

UMD tại sao nó quan trọng?

Đây là phần mình thấy nhiều bạn hay bỏ qua khi tự setup. UMD (Universal Module Definition) cho phép lib của bạn hoạt động trong ba môi trường khác nhau:

1// npm import (CommonJS/ES Module)
2import MyLibrary from 'my-library';
3
4// CDN / self-host (browser global)
5let MyLibrary = window.MyLibrary.default;
6let instance = new MyLibrary();
7
8// AMD (RequireJS)
9define(['my-library'], function(MyLibrary) { ... });

Nếu bạn tự config Webpack mà không cẩn thận, rất dễ ra một bundle chỉ chạy được trong một môi trường. Boilerplate này đã handle cái edge case đó rồi, bạn không cần lo.

Và với CSS, người dùng import thêm:

1import 'my-library/build/index.css';
2// hoặc qua CDN:
3// <link href="build/index.css" rel="stylesheet">

Proof of concept các lib thực tế build từ boilerplate này

Mình thấy cái này hay ở chỗ là README có luôn danh sách các library thực tế đã được build từ template này. Không phải demo toy project mà là những lib có người dùng thật:

• simple-keyboard Virtual keyboard thuần JS, khá popular
• react-simple-keyboard React version của cái trên
• hovercard Wikipedia summary cards
• redux-breeze Redux wrapper
• regex-colorizer Syntax highlighter cho regex

Đây là social proof tốt. Bạn biết template này đã được test trong production thực tế, không phải chỉ là một cái repo ai đó tạo ra rồi bỏ đó.

Điểm mạnh và hạn chế

Cái làm mình hài lòng:

Dependabot được bật sẵn và update hàng ngày đây là thứ mình hay quên setup khi tự tạo project. Với một boilerplate mà dependencies update liên tục (Webpack, Babel...), cái này quan trọng hơn bạn nghĩ.

Cái demo flow cũng rất clean. npm run demo build ra một trang demo hoàn chỉnh, ready để deploy lên GitHub Pages hay Netlify. Nhiều lib thiếu cái này và người dùng không biết lib đó làm gì.

Customizable file headers là một feature nhỏ nhưng professional. Build output của bạn sẽ có header comment với tên lib, version, author, license nhìn rất chỉn chu.

Hạn chế cần biết:

Theo kinh nghiệm của mình, boilerplate này hơi opinionated về CRA-based setup. Nếu bạn muốn một cái gì đó minimalist hơn chỉ Rollup + Babel thuần, không có phần demo app thì tác giả cũng có một repo khác là js-library-boilerplate-basic phù hợp hơn.

Ngoài ra, vì based on CRA, bundle size của demo app hơi lớn hơn cần thiết nếu bạn chỉ viết một utility lib nhỏ. Không ảnh hưởng đến bundle của lib thực tế, nhưng nếu bạn để ý thì sẽ thấy.

Anh em nên dùng cái này khi nào?

Dùng js-library-boilerplate nếu:

• Bạn đang build một React component library hoặc JS lib có CSS
• Bạn muốn có sẵn demo page để showcase
• Bạn cần support cả npm import lẫn CDN usage
• Bạn không muốn mất thời gian config Webpack từ đầu

Bỏ qua nếu:

• Bạn chỉ cần một utility function đơn giản, không có UI
• Bạn đang dùng Vite hoặc Rollup và đã quen với ecosystem đó
• Team bạn có convention riêng về project structure

Với 230 stars và một số library production thực tế build từ đây, đây là một template đáng tin cậy. Lần tới khi bạn bắt đầu một JS library mới, thay vì ngồi config Webpack từ đầu, clone cái này về, đổi tên, và bắt đầu code thứ quan trọng hơn.