Cách dễ nhất để tạo gói NPM đầu tiên của bạn

Hướng dẫn này sẽ hướng dẫn bạn quy trình dễ dàng nhất để xây dựng và phát hành gói NPM của bạn, từ đầu đến cuối, bằng cách sử dụng gói nhỏ .

Hãy nói một chút về nó microbundle . Tôi thấy nó đặc biệt hiệu quả đối với các thư viện đơn giản vì bạn không phải lo lắng về cấu hình, cho phép bạn tập trung vào việc phát triển gói của mình.

Dưới đây là danh sách ngắn các tính năng của nó:

• Cấu hình tích hợp; tất cả những gì bạn phải làm là thêm trường “xuất” vào package.json
• Hỗ trợ TypeScript ngay lập tức mà không cần tsconfig.json
• Nhiều định dạng đầu ra (CJS, UMD và ESM)
• Tính năng nén Terser tích hợp

Về cơ bản, microbundle được xây dựng dựa trên rollup.js . Nếu bạn cần xây dựng nhiều thư viện phức tạp hơn những gì tôi sẽ đề cập trong bài viết này, bạn có thể cân nhắc sử dụng cấu hình rollup.js thuần túy.

Khởi tạo gói của bạn

Ví dụ: hãy tạo một thư viện đơn giản để tính tổng hai số, thư viện này sẽ chỉ xuất một hàm sum .

1. Tạo một thư mục cho dự án và chạy npm init với các giá trị mặc định để tạo package.json

   
   

2. Tạo index.ts trong thư mục src

    // src/index.ts export function sum(a: number, b: number) { return a + b; }

3. Cài đặt microbundle

   npm i -D microbundle

   
   

4. Cập nhật package.json với các giá trị sau:

    // package.json ... "type": "module", "source": "src/index.ts", // your source code "exports": { "types": "./dist/index.d.ts", // TypeScript declaration file "require": "./dist/index.cjs", // CommonJS entry point "default": "./dist/index.esm.js" // ES Module entry point }, "main": "./dist/index.cjs", // where to generate the CommonJS bundle "module": "./dist/index.esm.js", // where to generate the ESM bundle "unpkg": "./dist/index.umd.js", // where to generate the UMD bundle "types": "./dist/index.d.ts", // TypeScript declaration file for the package "scripts": { "build": "microbundle", // compiles "source" to "main", "module", "unpkg" "dev": "microbundle watch" // re-build when source files change } ...

5. Chạy tập lệnh xây dựng

   npm run build

   
   

   Đầu ra phải chứa chính xác các tệp mà chúng tôi đã khai báo trong package.json

   

Và voilà, chúng tôi đã thực hiện gói hàng đầu tiên. Chúng ta hãy xem xét các kịch bản phức tạp hơn.

Thêm React vào thư viện của bạn

Nếu muốn đưa React vào thư viện của mình, bạn vẫn có thể sử dụng microbundle , nhưng bây giờ, lệnh xây dựng của bạn sẽ trông như thế này:

 microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx

Thêm lệnh vào package.json vào tập lệnh build để thuận tiện cho sau này:

 // package.json ... "scripts": { "build": "microbundle --jsx React.createElement --jsxFragment React.Fragment --jsxImportSource react --globals react/jsx-runtime=jsx" } ...

Sử dụng Storybook cho các thành phần giao diện người dùng

Trong khi xây dựng thư viện giao diện người dùng, bạn có thể cần một hộp cát nơi bạn có thể phát triển, trực quan hóa các thành phần và cung cấp các thành phần demo cho tài liệu của mình.

Đây là cuốn truyện . Đó là một hộp cát với giao diện và gói tiện lợi riêng, nơi bạn có thể dễ dàng mô tả các trạng thái khác nhau của các thành phần của mình. Mỗi lần nắm bắt trạng thái thành phần của bạn được gọi là một "câu chuyện".

Bức ảnh này, được lấy từ tài liệu của họ, cho thấy nó trông như thế nào:

Việc cài đặt Storybook khá đơn giản; chỉ cần chạy lệnh bên trong thư viện của bạn:

 npx storybook@latest init

Lệnh này sẽ cài đặt tất cả các phần phụ thuộc cần thiết cho Storybook, thêm tập lệnh để chạy và xây dựng Storybook thành package.json , tạo thư mục .storybook với cấu hình mặc định và thêm một số ví dụ về truyện vào thư mục src/stories .

Tích hợp kiểu dáng vào thư viện của bạn

Bạn có thể thêm kiểu dáng theo một trong hai cách: tệp CSS hoặc CSS-in-JS. Tệp CSS cho phép tùy chỉnh dễ dàng nhưng yêu cầu đưa vào riêng biệt, trong khi CSS-in-JS đơn giản hóa kiểu dáng nhưng tăng kích thước gói.

• tập tin CSS

  Tạo một tệp CSS trong thư mục src và nhập nó vào tệp thành phần phản ứng gốc:

   // src/index.tsx import './styles.css'; export const MySuperComponent = () => { return ( <h1 className="title">Hi there!</h1> ) };

  
  

  Vì vậy, hãy chạy lại lệnh build.

   npm run build

  
  

  Và tệp styles.css đã nhập của bạn sẽ được tạo trong thư mục dist :

  

  Tuyệt vời! Chúng ta đã có được một file CSS với các style cần thiết. Tuy nhiên, có một chút bất tiện với giải pháp này. Tệp CSS cần được thêm riêng sau khi cài đặt gói.

  
  

  Do đó, người dùng thư viện của bạn sẽ cần sử dụng trình tải CSS (ví dụ: trình tải CSS cho gói web) để xử lý tệp CSS của bạn và cách sử dụng của họ sẽ như sau:

   import { MySuperComponent } from 'my-super-library'; import 'my-super-library/dist/styles.css'; export const App = () => { return ( <MySuperComponent /> ); }

  
  

• CSS-trong-JS

  Bạn có thể sử dụng các thư viện như styled-comments cho mục đích này. Và nó sẽ trông như thế này:

   import styled from 'styled-components'; const Title = styled.h1` font-size: 30px; font-weight: bold; `; export const MySuperComponent = () => { return ( <Title>Hi there!</Title> ) };

  Với giải pháp này, người dùng sẽ không cần nhập tệp CSS và thêm trình tải đặc biệt cho dự án của họ. Sau khi cài đặt thư viện, thành phần sẽ có kiểu dáng riêng. Tuy nhiên, điều này sẽ làm tăng kích thước gói và khiến người dùng gặp khó khăn hơn trong việc tùy chỉnh các thành phần bằng bộ chọn CSS.

Chọn tùy chọn phù hợp với bạn nhất. Tôi thích sử dụng tệp CSS hơn vì nó cho phép người dùng tùy chỉnh bất kỳ thành phần nào bằng bộ chọn CSS, không ảnh hưởng đến kích thước gói và hoạt động nhanh hơn.

Phát triển tệp README.md chi tiết

Tệp README.md cung cấp thông tin về thư viện của bạn, cách cài đặt, cách sử dụng cơ bản và các tính năng mà nó có. Đây thường là tệp đầu tiên mà nhà phát triển đọc khi họ gặp kho lưu trữ hoặc gói NPM của bạn, vì vậy, tệp này phải ngắn gọn và chứa nhiều thông tin.

Tôi muốn tạo một cấu trúc theo thứ tự sau:

1. Tiêu đề
2. Mô tả gói siêu ngắn
3. Huy hiệu thống kê ưa thích ( Shields.io )
4. Nếu thư viện của bạn là một thành phần giao diện người dùng, hãy bao gồm ảnh chụp màn hình hoặc cung cấp liên kết demo trên CodeSandbox
5. Danh sách tính năng
6. Hướng dẫn cài đặt
7. Các đoạn mã có cách sử dụng
8. Các tùy chọn và đạo cụ mà thư viện của bạn chấp nhận để cấu hình

Bạn có thể tham khảo các ví dụ về tệp README.md từ các gói của tôi, chẳng hạn như dot-path-value và Reac-nested-dropdown để lấy cảm hứng.

Điều hướng quản lý phụ thuộc

Đây là phần quan trọng vì nếu làm sai, người dùng có thể gặp phải tình trạng xung đột phiên bản hoặc các vấn đề khác và họ sẽ phải xóa thư viện của bạn. Vì vậy, chúng ta hãy xem xét sự khác biệt chính giữa các loại phụ thuộc.

• “devDependency” chỉ dành cho việc phát triển và sẽ không được đưa vào gói của bạn. Ví dụ: nếu bạn đã cài đặt gói microbundle mà người dùng không cần sử dụng, hãy giữ gói đó trong devDependency và nó sẽ không xuất hiện trong gói.

• "phụ thuộc" sẽ được cài đặt cùng với gói. Bao gồm các phần phụ thuộc mà gói của bạn cần để hoạt động trong các dự án của người dùng. Lưu ý rằng một số phần phụ thuộc, chẳng hạn như “react”, có thể đã được cài đặt trong dự án của người dùng. Việc có một "phản ứng" trùng lặp trong gói của bạn có thể tăng kích thước gói. Đây chính là lúc “phụ thuộc ngang hàng” phát huy tác dụng.

• “Phụ thuộc ngang hàng” là các phần phụ thuộc mà gói của bạn sử dụng nhưng sẽ không đưa vào gói của bạn. Gói của bạn sẽ sử dụng phiên bản phụ thuộc mà người dùng có trong dự án của họ.

  
  

  Về cơ bản, chúng ta nên chỉ định một phần phụ thuộc ngang hàng nếu chúng ta đang tạo một thư viện cho hệ sinh thái của nó. Ví dụ: nếu bạn đang tạo thành phần React, hãy đặt React làm thành phần phụ thuộc ngang hàng. Nếu phát triển thành phần React có lịch, hãy thêm React và thư viện tính toán ngày (ví dụ: date-fns) làm các phụ thuộc ngang hàng.

  
  

  Nếu người dùng không có phần phụ thuộc ngang hàng được chỉ định trong dự án của họ, lệnh npm install sẽ hiển thị cảnh báo, nhưng nó sẽ không tự động cài đặt phần phụ thuộc.

Chỉ là một ví dụ nhỏ về giao diện của nó:

 // package.json ... "dependencies": { // libraries which will be installed along with your library "clsx": "^1.2.1" // just library for className combining }, "peerDependencies": { // user should have these packages installed "react": "^16.8.0 || ^17.0.0 || ^18.0.0" // user should have react 16.8+ version }, "devDependencies": { // won't be in user's bundle, these libraries just for your developing needs "@types/react": "^18.2.33", "react": "^18.2.0", // in case if we are using storybook, we need actual react library to render our components there "microbundle": "^0.15.1", }, ...

Sử dụng GitHub cho gói của bạn

Nếu bạn đang xuất bản gói NPM, điều đó có nghĩa là nó sẽ có thể truy cập công khai (nếu bạn có tài khoản miễn phí). Để thu thập phản hồi từ người dùng, bạn có thể tạo kho lưu trữ GitHub cho mã gốc của mình. Mọi người có thể tạo ra vấn đề và liên lạc với bạn về gói hàng của bạn ở đó. Bạn cũng có thể mô tả các bản phát hành của mình và nhận được một số ngôi sao!

Bạn chắc chắn có thể bỏ qua bước này, nhưng nó là một phần không thể thiếu trong văn hóa nhà phát triển và có thể là đóng góp có giá trị cho nguồn mở.

Xuất bản và duy trì gói

Trước khi bạn có thể xuất bản gói của mình, điều cần thiết là phải đảm bảo rằng tệp package.json của bạn được định cấu hình đúng cách. Dưới đây là một số bước quan trọng cần làm theo:

1. Đặt tên và cố gắng mô tả chức năng cốt lõi của thư viện của bạn. Ví dụ:

    "name": "react-color-picker"

   
   

2. Thêm thông tin kho lưu trữ GitHub (nếu nó tồn tại):

    ... "homepage": "https://github.com/{your_repository}", "repository": { "type": "git", "url": "https://github.com/{your_repository}" }, "bugs": { "url": "https://github.com/{your_repository}/issues" }, ...

   
   

3. Cấu hình files :

    ... "files": [ "dist", ], ...

   Bạn nên chỉ định các tệp sẽ được bao gồm trong node_modules khi thư viện của bạn được cài đặt. Thông thường, bao gồm cả thư mục dist là đủ.

   
   

4. Thêm keywords :

   Từ khóa là một chuỗi các chuỗi mô tả gói của bạn và được NPM sử dụng để tìm kiếm và đề xuất. Chọn những từ có liên quan đến gói hàng của bạn mà bạn dự đoán mọi người sẽ sử dụng khi tìm kiếm. Hãy tạo từ khóa cho thư viện sum của chúng tôi:

    ... "keywords": ["typescript", "math", "sum", "numbers", "arithmetic", "calculator", "calculation"] ...

   Điều quan trọng là chỉ định công nghệ của bạn vì người dùng thường tìm kiếm các cụm từ như “thư viện bản thảo cho toán học” hoặc “bộ chọn lịch phản ứng”.

   
   

5. Tạo một tài khoản NPM nếu bạn chưa có và chạy npm login trong terminal của bạn; làm theo lời nhắc để xác thực tài khoản của bạn. Theo mặc định, phiên bản gói của bạn sẽ là 1.0.0 ; bạn có thể kiểm tra nó trong tệp package.json . Tôi khuyên bạn nên thay đổi nó thành 0.0.1 .

   
   

6. Chạy npm publish và bạn đã hoàn tất! Để cập nhật phiên bản trong tương lai, hãy sử dụng lệnh npm version patch để tăng phiên bản, sau đó xuất bản gói đã cập nhật bằng npm publish .

Phần kết luận

Như bạn có thể thấy, việc tạo thư viện của riêng bạn rất dễ dàng! Về cơ bản, đây là tất cả những gì bạn cần để tạo và duy trì gói. Nếu bạn gặp khó khăn trong việc giới hạn thư viện của mình bằng microbundle , tôi khuyên bạn nên sử dụng rollup.js với cấu hình cụ thể hơn.

Tạo các gói NPM và đóng góp cho nguồn mở là một trải nghiệm bổ ích và có giá trị đối với các nhà phát triển thuộc mọi cấp độ kỹ năng. Nó cho phép bạn chia sẻ mã của mình với cộng đồng, tích lũy nhiều kinh nghiệm và xây dựng danh mục công việc của bạn.