Tutorial: Cara Mempublikasikan Paket NPM Pertama Anda

NPM

NPM atau Node Package Manager adalah registri perangkat lunak terbesar di internet. NPM sebenarnya lebih dari sekadar registry. NPM juga mencakup alat pengelolaan paket dan repositori paket. Jadi, sementara registry NPM adalah tempat di mana paket-paket Javascript dipublikasikan dan dapat diunduh, NPM secara keseluruhan adalah ekosistem yang mencakup alat untuk menginstal, mengelola, dan mempublikasikan paket-paket tersebut. Dengan kata lain, NPM adalah alat yang memungkinkan pengembang untuk mengelola ekosistem pengembangan perangkat lunak Javascript.

Pada artikel ini, kita akan mempelajari cara membuat paket NPM dan mempublikasikanya sehingga orang lain dapat mengunduh dan menggunakanya.

Pemilihan Nama Paket

Nama paket pada NPM bersifat unik sehingga jika sudah ada paket dengan nama hello-pack maka anda tidak bisa membuat dan mempublikasikan paket baru dengan nama yang sama dengan hello-pack. Untuk memastikan apakah nama paket yang akan dibuat sudah terpakai atau belum, anda bisa mengeceknya langsung di NPM registry atau bisa juga dengan cara npm search <nama-paket>, misalnya paket class-validator.

npm search class-validator

Maka, akan memunculkan paket dengan nama class-validator. Sedangkan ketika kita cari paket dengan nama num-checker, maka yang akan muncul,

No matches found for "num-checker"

Itu artinya paket num-checker belum pernah dipublikasikan di registri NPM.

Membuat Paket Anda Sendiri

Agar lebih mudah, paket yang akan dibuat bernama num-checker. Paket ini berisi fungsi isOdd dan isEven yang berguna untuk menentukan apakah sebuah angka adalah negatif atau positif.

Membuat Folder dan Inisiasi proyeknpm.

Paket akan disimpan dalam sebuah folder dengan nama num-checker-package, caranya:

mkdir num-checker-package
cd num-checker-package

Pemberian nama folder ini tidak harus sama dengan nama paket. Selanjutnya, kita inisiasi npm dengan cara:

npm init

Setelah enter maka akan muncul beberapa pertanyaan seperti:

package-name
Nama paket harus diisi dengan aturan kebab-case. Bagian ini diisi dengan num-checker.
version
Versi proyek adalah nomor versi proyek yang menggambarkan keadaan proyek anda. Misalnya, ketika proyek ini baru dibuat dan belum ditest secara lanjut maka sebaiknya diisi dengan 0.0.1 sementara jika sudah melewati pengujian lanjut sebaiknya diisi dengan 1.0.0. Bagian ini diisi dengan 0.0.1.
description

Deskripsi berisi penjelasan singkat mengenai paket. Bagian ini diisi bebas.

Setelah enter maka akan menghasilkan sebuah file package.json yang berisi seperti berikut.

{
  "name": "num-checker",
  "version": "0.0.1",
  "description": "library for check number",
  "main": "main.js",
  "keywords": [
    "odd",
    "even",
    "isOdd",
    "isEven",
    "checker"
  ],
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Sekhudin/num-checker-package.git"
  },
  "author": "sekhudin",
  "license": "ISC"
}

Membuat Folder src dan tests. Folder src adalah lokasi dimana kode Javascript akan disimpan. Sementara folder tests adalah folder dimana script test pengujian kode disimpan.

mkdir src
mkdir tests

Kemudian, Buatlah sebuah file main.js, simpan di dalam folder src. File main.js berisi kode berikut:

/**
 * IsOdd will return true if the number is odd.
 * @param {*} num - number
 * @returns boolean
 */
export function isOdd(num) {
  if (num === 0) return false;
  if (num < 0) {
    return num % -2 !== 0;
  }
  return num % 2 !== 0;
}


/**
 * IsEven will return true if the number is even.
 * @param {*} num - number
 * @returns boolean
 */
export function isEven(num) {
  return !isOdd(num)
}

Selain itu, untuk memberi dukungan type untuk Typescript, anda perlu menambahkan file berisi deklarasi tipe. Nama file paling umum adalah index.d.ts, berada satu folder dengan file main.js. File tersebut berisi seperti ini:

declare module 'num-checker' {
  export function isOdd(num:number): boolean;
  export function isEven(num:number): boolean;
}

Susunan struktur proyek anda akan menjadi seperti ini:

num-checker-package
└───node_modules
└───src
│   │ main.js
|   | index.d.ts
│   
└───tests
|
|   README.md
|   package.json

Instalasi babel dan jest.

Kode fungsi isOdd dan isEven memerlukan pengujian dan transpilasi. Tujuan dari pengujian adalah memastikan fungsi yang dibuat memiliki output yang konsisten. Sementara transpilasi bertujuan menghasilkan kode JavaScript yang kompatibel dengan lingkungan runtime yang lebih lama atau berbagai browser yang mungkin tidak mendukung fitur-fitur terbaru dari Javascript. Jadi, nantinya kode yang akan anda publish adalah kode Javascript hasil transpilasi. Untuk melakukan pengujian anda memerlukan jest dan babel untuk transpilernya.

Instalasi jest dan babel:
```
 nmp i --save-dev @babel/core @babel/cli @babel/preset-env babel-jest jest
```
Penambahan --save-dev artinya jest dan babel hanya akan ditambahkan ke dependensi pengembangan sehingga tidak akan terinstall jika paket num-checker diunduh orang lain. Setelah instalasi jest dan babel, file package.json akan memiliki kunci devDependencies berisi daftar dependensi pengembangan yang digunakan.

Konfigurasi babel, jest dan konfigurasi lain.

Selanjutnya, anda perlu melakukan sejumlah konfigurasi tambahan.

Tambahkan file bernama .babelrc untuk konfigurasi babel dan berisi seperti ini,

 {
   "presets": ["@babel/preset-env"]
 }

Kemudian tambahkan file jest.config.js untuk konfigurasi jest dan berisi seperti ini,

 module.exports = {
   roots: ['<rootDir>/tests'],
   testMatch: ['**/*.test.js', '**/*.spec.js'],
   transform: {
     '^.+\\.js$': 'babel-jest',
   },
   testEnvironment: 'node'
 };

Kemudian tambahkan file .npmignore untuk memaksa NPM mengabaikan folder dan file tertentu agar tidak ikut terpublish ke NPM registry. Isi file tersebut seperti ini (file yang tercantum bisa berbeda-beda setiap paket).

 # Ignore file konfigurasi
 .babelrc
 .gitignore
 .npmignore
 jest.config.js

folder node_modules tidak perlu dimasukan karena akan otomatis diabaikan ketika publikasi paket. Terakhir, anda perlu mengubah isi package.json agar seperti ini:

 {
   "name": "num-checker",
   "version": "0.0.1",
   "description": "library for check number",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "babel src --out-dir dist && cp src/index.d.ts dist/",
     "test": "jest"
   },
   "files": [
     "dist/main.js",
     "dist/index.d.ts"
   ],
   "keywords": [
     "odd",
     "even",
     "isOdd",
     "isEven",
     "checker"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Sekhudin/num-checker-package.git"
   },
   "author": "sekhudin",
   "license": "ISC",
   "devDependencies": {
     "@babel/cli": "^7.23.9",
     "@babel/core": "^7.24.0",
     "@babel/preset-env": "^7.24.0",
     "babel-jest": "^29.7.0",
     "jest": "^29.7.0"
   }
 }

Pada bagian scriptsbuild digunakan untuk perintah transpilasi file src/main.js dan menyimpanya pada folder dist, selain itu akan menyalin file index.d.ts pada folder dist juga.

Menulis testing, file pengujian.

Untuk menulis testing, buatlah file dengan nama akhiran *.test.js di dalam folder tests misalnya main.test.js untuk menguji fungsi isOdd dan isEven yang ada pada src/main.js, sehingga script pengujianya seperti ini:

```javascript import { isEven, isOdd } from '../src/main';

describe('isOdd test zero', () => { test('0 should be false', () => { expect(isOdd(0)).toBe(false) }); });

describe('isOdd test negative', () => { test('-1 should be true', () => { expect(isOdd(-1)).toBe(true) }); });

describe('isOdd test positive', () => { test('1 should be true', () => { expect(isOdd(1)).toBe(true) }); });

describe('isEven test zero', () => { test('0 should be true', () => { expect(isEven(0)).toBe(true) }); });

describe('isEven test negative', () => { test('-2 should be true', () => { expect(isEven(-2)).toBe(true) }); });

describe('isEven test positive', () => { test('2 should be true', () => { expect(isEven(2)).toBe(true) }); });


6. Menjalankan transpilasi dan test

    Untuk menjalankan transpilasi maka jalankan:

    ```bash
    npm run build

Ketika script build dijalankan maka akan menghasilkan folder dist yang berisi hasil transpilasi. Kemudian, untuk menjalankan pengujian maka jalankan:

    npm run test

Jika pengujian berhasil maka, tidak akan ada error, pengujian hanya akan memunculkan centang hijau saja pertanda success.

File Dokumentasi dan LICENSE.

Dua file ini bersifat opsional, namun sebaiknya tetap ada. Dokumentasi adalah aturan bagaimana cara menggunakan paket num-checker. File dokumentasi biasanya berupa file README.md dan penulisan menggunakan markdown.

Struktur folder setelah transpilasi dan testing:

 num-checker-package
 └───node_modules
 └───dist
 │   │ main.js
 |   | index.d.ts
 |
 └───src
 │   │ main.js
 |   | index.d.ts
 │   
 └───tests
 |   | main.test.js
 |
 |   .babelrc
 |   .npmignore
 |   README.md
 |   jest.config.js
 |   package-lock.json
 |   package.json

Mempublikasikan paket num-checker.

Folder dan file mana saja yang akan ter-publish ?

Folder dan file berikut yang akan tepublish, antara lain:

num-checker-package
└───dist
│   │ main.js
|   | index.d.ts
|
|   README.md
|   package.json

Untuk mempublikasikan paket, anda harus login dulu, caranya:

npm login

Anda akan diarahkan untuk login. Isilah username dan password anda.

Untuk memastikan apakah anda sudah login, anda dapat menjalankan perintah berikut:

npm whoami

Jika anda ingin menampilkan daftar file dan folder yang akan dipublikasin, anda dapat menjalan perintah berikut:

npm pack --dry-run

Jika file dan folder sudah sesuai saatnya publikasi. untuk melakukan publikasi, anda hanya perlu menjalankan perintah berikut:

npm publish

Ketika publikasi berhasil maka akan muncul seperti ini (Gambar hanya contoh):

Catatan:

Seharusnya paket num-checker sudah ada, jadi anda harus mengganti nama paket anda dengan nama yang unik.

Github: sekhudin/num-checker

https://www.syaikhu.com

Syaikhu's Insight Hub

Syaikhu's Insight Hub

Paket NPM Pertamamu

Table of contents

NPM

Pemilihan Nama Paket

Membuat Paket Anda Sendiri