HƯỚNG DẪN PUBLISH JAVASCRIPT PACKAGE LÊN NPM

NPM (Node Package Manager) là một công cụ tạo và quản lý các thư viện lập trình Javascript cho Node.js. Các lập trình viên phát triển các NPM package và publish lên server của NPM để sử dụng và chia sẻ với cộng đồng. Bạn thường xuyên sử dụng lệnh npm install <packageName> để cài đặt các thư viện từ NPM rồi đúng không? Có khi nào bạn tự hỏi mình có thể tự viết các package để tái sử dụng, chia sẻ cho đồng nghiệp và đóng góp cho cộng đồng lập trình viên chưa? Trong bài viết này, mình sẽ chia sẻ với bạn các bước để publish một javascript package với NPM.

(Lưu ý: Các kiến thức bạn nên có trước khi tham khảo thông tin bài viết: Cài đặt và sử dụng NPM (cơ bản), Kiến thức về GIT (cơ bản), Kiến thức về Javascript (cơ bản). Chúng đều là tiền đề để bạn có thể dễ dàng tiếp cận những nội dung được trình bày tiếp theo).

Bước 1: Lập tài khoản NPM

Đăng ký tài khoản npm tại đây. Đây là nơi chúng ta sẽ đẩy package và quản lý chúng.

Bước 2: Tạo Reposiory git

Tạo repository tại github. Package của bạn cần nằm trong 1 reposiry dạng pulic. Đây sẽ là trang giúp chúng ta quản lý mã nguồn và tài liệu hướng dẫn sử dụng package.

Bước 3: Tạo thư mục package

Bạn cần tạo một thư mục là tên của package bạn muốn viết. Cấu trúc bên trong thư mục của 1 package rất đơn giản với 2 file sau:

json: khai báo thông tin về package
js: viết theo cấu trúc module, export các thành phần. Khi require package chính là thực hiện require file này.

Bước 4: Tạo package

Để mọi người hiểu nhanh, sau đây chúng ta sẽ thử làm một package đơn giản về việc random quân trong game Đế chế (AOE). Mình lựa chọn ví dụ này bởi vì số lượng người biết tới game này khá đông đảo. Bạn có thể xem trước phần demo và source code tại đây nhé:

Demo random AOE tại đây
Source Github tại đây

4.1. Tạo file package.json

Đầu tiên ta tạo thư mục aoerandom và file package.json để lưu trữ cấu hình thông tin của package. Khởi tạo nhanh bằng câu lệnh npm init -y, ta có ngay file package.json với nội dung sau:

{

  "name": "aoerandom",

  "version": "1.0.0",

  "description": "",

 "main": "index.js",

  "scripts": {

    "test": "echo \"Error: no test specified\" && exit 1"

  },

  "keywords": [],

  "author": "",  "license": "ISC"

}

Name: chính là tên package bạn muốn đặt. Mặc định nó đang lấy tên thư mục chứa file package.json
Version: tên phiên bản hiện tại của package. Mặc định là 1.0.0
Description: thông tin, giới thiệu về package
Main: đấy chính là file viết theo cấu trúc export. Mặc định là index.js.Khi bạn require package chính là bạn require file này
Scripts: định nghĩa các command local của package
Keywords: các từ khóa liên quan tới package, giúp cho việc tìm kiếm package của bạn được dễ dàng. Keyword sẽ góp phần giúp nhiều người biết đến package của bạn nhiều hơn.
License: bản quyền của package.

Với package này, cấu trúc của mình sẽ như sau:

{

  "name": "aoerandom",

  "version": "1.0.0",

  "description": "Hỗ trợ game thủ random quân, tạo kèo đấu trong game AOE",

  "main": "index.js",

        "homepage": "https://github.com/FightLightDiamond/aoerandom",

  "scripts": {

    "test": "echo \"Error: no test specified\" && exit 1"

  },

  "keywords": [

    "AOE",

    "GAME",

    "RANDOM",

    "JS",

    "Age of Empires",

    "CUONGPM",

    "FightLightDiamond"

  ],  "author": "FightLightDiamond",

  "license": "ISC"

}

Phần homepage chính là link github của package.

4.2 Nội dung của chương trình

Tiếp theo, mình tạo file index.js với nội dung như sau:

// Các loại quân trong AOE

const items = [

    'Egyptian',

    'Greek',

    'Babylonian',

    'Assyrian',

    'Minoan',

    'Hittite',

    'Phoenician',

    'Sumerian',

    'Persian',

    'Shang',

    'Yamato',

    'Choson',

    'Carthaginian',

    'Palmyran',

    'Macedonia',

]; 

// Lấy ngẫu nhiên một loại quân

getCountryRandom = () => {

    const randomIndex = Math.floor(Math.random() * items.length);

    return items[randomIndex];

} 

// Random cho một Team.getTeamRandom = (length) => {

    let countries = [];

     for (let i = 1; i <= length; i++) {

        const item = getCountryRandom()

         countries.push(item)

    }

     return countries;}

 

exports.getCountryRandom = getCountryRandom

exports.getTeamRandom = getTeamRandom

Ví dụ khá dễ hiểu phải không? Và với dữ liệu đầu vào là các loại quân trong game. Chúng ta có 2 hàm sau đây:

getCountryRandom: Ra một quân random. Sử dụng trong lối chơi solo, một người random trước, rồi người sau sẽ tự động chọn quân khắc chế. Ví dụ: A: Greek, thì B: chọn Egyptian.
getTeamRandom: Ra nhiều random tùy theo số lượng người chơi. Sử dụng trong lối chơi team.

4.3. Cài đặt Package global (command)

Khi cài một package global với tham số -g, chúng ta sẽ sử dụng các command của package:

aoerandom <số người chơi>
```
Tiếp theo, cùng tạo thư mục commands (thư mục danh riêng cho file command), tạo file command aoerandom.jsvới nội dung như sau:
```
#!/usr/bin/env node

// require để sử dụng hàm random đã được viết

const aoe = require('../index.js')

// hàm radom random = (num) => {

num = parseInt(num);

console.log('You want random team size is ' + num)

  if(num > 8 || num <1 || num === undefined || isNaN(num)) {

    console.log("Số game thủ của game từ 1 đến 8. Bạn vui lòng thử lại!")

    return

}

  for (let i = 1; i <= num; i++) {

    const item = aoe.getCountryRandom()

     console.log(i, item);

 }

} 

// lấy parameter

const argvs = process.argv 

// Từ index số 2 là tham số chúng ta truyền vào, ở đây là số người chơi.

random(argvs[2])

Để NPM hiểu được command, chúng ta cần tiếp tục khai báo với package.json như sau

"bin": {

    "aoerandom": "commands/aoerandom.js"

  },

Chi tiết:

{

  "name": "aoerandom",

  "version": "1.0.0",

  "description": "Hỗ trợ game thủ random quân, tạo kèo đấu trong game AOE",

  "main": "index.js",

        "homepage": "https://github.com/FightLightDiamond/aoerandom",

  "scripts": {

    "test": "echo \"Error: no test specified\" && exit 1"

  },

        "bin": {

    "aoerandom": "commands/aoerandom.js"

  },

  "keywords": [

    "AOE",

    "GAME",

    "RANDOM",

    "JS",

    "Age of Empires",

    "CUONGPM",

    "FightLightDiamond"

  ],

  "author": "FightLightDiamond",

  "license": "ISC"

}

4.4. Testing ở local trước khi publish

Trước khi publish package, hãy test thử bằng cách publish lên máy local với command npm link nhé.

Kết quả từ command trả về:

npm notice created a lockfile as package-lock.json. You should commit this file.

npm WARN aoerandom@1.0.0 No description

npm WARN aoerandom@1.0.0 No repository field.

up to date in 1.002s

found 0 vulnerabilities


/usr/local/bin/aoerandom ->

/usr/local/lib/node_modules/aoerandom/commands/aoerandom

/usr/local/lib/node_modules/aoerandom ->

/Users/adminadmin/ad/Repositories/api/aoerandom

Tiếp theo, ta test thử random quân cho 1 kèo 4-4 tương ứng với 8 người chơi

 aoerandom 8

Kết quả trả về:

1 'Macedonia'

2 'Phoenician'

3 'Persian'

4 'Egyptian'

5 'Carthaginian'

6 'Phoenician'

7 'Choson'

8 'Yamato'

Quân bài khá đẹp cho team 1 phải không? Ta cùng thử lần 2 xem sao nhé.

1 'Minoan'

2 'Macedonia'

3 'Carthaginian'

4 'Babylonian'

5 'Palmyran'

6 'Hittite'

7 'Egyptian'

8 'Shang'

Ngược lại nếu bạn muốn gỡ nó ra thì đơn giản với câu lệnh

npm unlink

Bước 5: Publish package lên NPM

Đầu tiên, bạn sẽ cần đăng nhập vào npm.

 npm login

Tiếp theo, cùng đẩy package lên để chia sẻ với mọi người nhé. Nếu đây là lần đầu tiên publish package trên NPM, bạn sẽ cần xác nhận với địa chỉ email đã đăng ký.

npm publish

npm notice

npm notice 📦  aoerandom@1.0.0

npm notice === Tarball Contents ===

npm notice 383B commands/aoerandom.js

npm notice 773B index.js

npm notice 408B package.json

npm notice 524B readme.md

npm notice === Tarball Details ===

npm notice name:          aoerandom

npm notice version:       1.0.0

npm notice package size:  1.2 kB

npm notice unpacked size: 2.1 kB

npm notice shasum:        d13d1c06b6c0c740d2b86cd42784ca245fa4468a

npm notice integrity:     sha512-XvzLz0J2q2Hgv[...]7h+XxvdZ2JL3g==

npm notice total files:   4

npm notice + aoerandom@1.0.0

Vậy là bạn đã publish package thành công rồi. Bây giờ, thử truy cập lại website của npm để kiểm tra package của bạn đã xuất hiện hay chưa nhé. Package khi được publish trông sẽ như thế này: LINK

Bước 6: Sử dụng package

Bây giờ chúng ta có thể sử dụng package vừa làm để tạo ra một trang random AOE rồi. Cài đặt để sử dụng như sau:

// cài đặt local

npm i -S aoerandom

// cài đặt global để sử dụng command

npm i -g aoerandom

Bạn có thể sử dụng package được rồi

// ES5

  const aoerandom = require('aoerandom')

// ES6

  import aoerandom from 'aoerandom';

  import {getCountryRandom, getTeamRandom} from 'aoerandom';

Chúng ta thấy rằng viết và publish một package với NPM rất nhanh và đơn giản phải không? Đã là lập trình viên thì chắc hẳn ai cũng có nhiều mã nguồn tâm đắc muốn chia sẻ, vậy thì tại sao không tạo ngay một package mang dấu ấn của riêng mình ngay hôm nay?