Futtatható bináris készítése Node.js alkalmazásból

Némi előkészületet azért igényel a csomagolás, de viszonylag könnyen elvégezhető. Néhány megkötése azért van a folyamatnak, így a következő dolgokra oda kell figyelnünk, ha csomagolni szeretnénk az alkalmazást:

1. A pkg tool jelenleg kizárólag ES5 dialektikájú (az elterjedt terminológiával élve CommonJS) forráskódot tud csomagolni. Természetesen ez nem azt jelenti, hogy csak ES5-ben írhatjuk meg az alkalmazást, viszont a csomagolás előtt le kell majd fordítani a forráskódot - erre a babel nevű toolt fogjuk használni.
2. Az előző pontból kifolyólag semmilyen utalás sem maradhat a kódban EcmaScript Module-okra (ESM). Ez elsősorban azt jelenti, hogy import utasításokkal nem importálhatunk függéseket és JS fájlokat, minden esetben a require utasításokra kell támaszkodnunk. A babel fordítás során ezek persze ki lesznek cserélve a kódban, de figyeljünk rá oda, hogy ha a kódban valahol import.meta hívásokat használtunk, azzal a babel nem fog kezdeni semmit, viszont a fordítás sem áll meg emiatt, csupán figyelmeztetéseket kapunk majd.
3. A csomagoláshoz a pkg-nak látnia kell a teljes függésfát az alkalmazás JS fájlai között, így például dinamikus importálások vagy külső konfigurációs fájlra támaszkodó dependency injection framework használata esetén explicit meg kell mondanunk a toolnak, hol vannak a fájlaink.
4. Ugyanez vonatkozik a statikus fájlokra, asset-ekre (képfájlok, CSS fájlok, "beégetett" konfigurációs fájlok, stb.)

Most, hogy tisztában vagyunk a feltételekkel, lássuk, hogyan tudunk hozzákezdeni a folyamathoz.

1. Telepítsük a szükséges tool-okat
   Adjuk hozzá az alkalmazás dev függéseihez (vagy telepítsük globálisan) a következőket: @babel/cli, @babel/core, @babel/preset-env és pkg.

npm install -g @babel/core
npm install -g @babel/cli
npm install -g @babel/preset-env
npm install -g pkg

A babel-nek emellett szüksége lesz egy pici konfigurációs fájlra, melyet .babelrc néven a projekt gyökerében kell elhelyeznünk, tartalma pedig az alábbi legyen:

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

2. Fordítsuk le a forráskódot ES5 (CommonJS) dialektikára
   A toolnak a forrásfájlok helyét kell megadni (ez esetben az src mappa az), illetve -d kapcsolóval azt a mappát, ahova a lefordított forráskódokat mentheti.

npx babel src -d build/target

3. (Opcionális) Másoljuk az asseteket a lefordított forrásfájlok mellé
   Ügyeljünk arra, hogy a becsomagolt alkalmazás ezeken az útvonalakon keresi majd az adott fájlokat. A Domino esetében például egy DI konfigurációs JSON fájlt kell mellékelnem, mely a belépési pontot jelentő domino_main.js fájl mellett levő config nevű mappában helyezkedik el. Ha nincs semmi ilyen fájlunk, ez a lépés teljes ki is maradhat. A példánál maradva, ez szimplán így néz majd ki:

mkdir build/target/config
cp config/di_config.json build/target/config/di_config.json

4. Állítsuk be a szükséges opciókat a pkg számára
   Ehhez a package.json-ban kell felvennünk néhány paramétert. Egyrészt a gyökérben vegyük fel a bin nevű paramétert, melyben a (lefordított) alkalmazás belépési pontját kell megadnunk.

{
  ...
  "bin": "build/target/app.js",
  ...
}

Majd vegyük fel a pkg-nak szóló további beállításokat, szintén a gyökérben elhelyezett pkg kulcs alatt:

  "pkg": {
    "assets": ["./build/target/config/di_config.json"],
    "scripts": "./build/target/**/*.js"
  },

Amennyiben vannak statikus asseteink, az assets paraméter kritikus fontosságú, enélkül a pkg nem fogja azokat becsomagolni. Az útvonalnak természetesen ez esetben a csomagolásra váró, lefordított forráskódokat tartalmazó mappára kell mutatnia. A scripts paraméter abban az esetben fontos, ha a függésfa nem egyértelműen feloldható. A paraméter értéke egy glob formátumú útvonal pattern - a fenti példa azt jelenti, hogy a ./build/target mappában és annak rekurzívan minden almappájában található összes .js kiterjesztésű fájlt használni szeretnénk a csomagolás során.

Fontos megjegyezni, hogy a legtöbb paraméter megadható a pkg tool parancssori argumentumaként is - én személy szerint vegyesen használom őket, nem feltétlenül követendő példa, jobb egységesíteni. :)

5. Jöhet a csomagolás
   Az alábbi parancs elindítja a csomagolást. A --targets kapcsolóval szabályozhatjuk, milyen cél operációs rendszerrel dolgozunk (ez esetben standard Linux kompatibilis binárist készítünk), az --output kapcsoló értelemszerűen az elkészült bináris mentési helyét adja, a parancs végén a . pedig szimplán azt jelenti, hogy "használd a jelenlegi mappát". Ez esetben mindenképp szüksége van a package.json fájl jelenlétére, illetve abban a bin paraméter is kritikus fontosságú. Ha a . helyett az alkalmazás belépési pontját képző .js fájlt adjuk meg, akkor a bin paraméter elhagyható.

npx pkg --targets=linux --output=build/out/app .

És készen is vagyunk! Az így elkészült bináris ugyanúgy futtatható, mint bármilyen más (ez esetben Linux) bináris. Természetesen a tool képes Windows és MacOS rendszerekre is csomagolni. A futtatáshoz pedig természetesen nem lesz szükségünk Node.js futtatókörnyezet telepítésére, mivel az is be van csomagolva a binárisba - éppen ebből az okból a Node.js által használt standard környezeti változók (NODE_ENV, NODE_CONF_DIR, stb.) továbbra is használhatóak.

A pkg tool működése kapcsolókkal még tovább finomhangolható, az alább linkelt dokumentációban azokról is találhattok bővebb információt, illetve még további példákat is.

Teljes példa a Domino alkalmazáshoz

pkg tool dokumentáció

Komment írásához jelentkezz be
Bejelentkezés