npm package: @nginstack/build-tools
Description: Auxiliary tools used for build JAZ packages on nginstack platform.
Latest version: 83.0.17

# Build Tools

Auxiliary tools used for build JAZ packages on nginstack platform.

## Install

### Prerequisites

* [Node.js](https://nodejs.org) 16 or greater.

### Installation

1. Install **@nginstack/build-tools** using npm:

    ```bash
    npm install @nginstack/build-tools
    ```

### Configuration

Build tools scripts requires a configuration about the target database that will run the tests and 
receive the build artifacts. The configuration can be informed by environment variables or 
by a *.env* config file placed at repository root. 

The build API and scripts will search custom jaz archives automatically at directory *build/* and 
they will use directory *.engine* as Engine work directory. It´s recommended to ignore this directory
in *.gitignore* to avoid to commit Engine large temporary files like logs and database local caches. 

Configure defining the environment variables:

* `ENGINE_URL`: engine server URL. Example: *http://my\_database.nginstack.com*. 
* `ENGINE_DATABASE`: database name. Example: *MY\_DATABASE*.
* `ENGINE_AUTH_TOKEN`: authorization token with permission to scope "api.devops". 

Alternatively, the variables below can be used instead of `ENGINE_AUTH_TOKEN`.

* `ENGINE\_USERNAME`: user name used to upload artifacts and run tests. 
* `ENGINE\_PASSWORD`: user password used to upload artifacts and run tests.

A *.env* file can also be used:

```
ENGINE_URL=http://my_database.nginstack.com
ENGINE_DATABASE=MY_DATABASE
ENGINE_AUTH_TOKEN=token
```

## Build and utilities scripts

### uploadToVfs

Upload one or more build artifacts to Engine Virtual File System.

**Usage**: 

```sh
uploadToVfs PATH_1 FILE_KEY_1 PATH_2 FILE_KEY_2 ... PATH_N FILE_KEY_N
```


### runTests

Run server tests on Engine and save the results to a file using the JUnit tests XML report file 
format.

**Usage**: 

```sh
runTests.js TESTS_PATHS OUT_REPORT_PATH
```    

**Experimental**: inform the parameter `-v8` to run tests using the V8 as default JavaScript 
runtime.

```sh
runTests.js TESTS_PATHS OUT_REPORT_PATH -v8
```

### installJazDependencies

Read the array property **jazDependencies** of *package.json* and download the informed JAZ 
packages of the server informed by the environment variable **SERVER\_URL**.
The downloaded JAZ packages are extracted in *node_modules*.

Is recommended to use installJazDependencies as a *postinstall* script of *package.json*.

**Usage**: 

```sh
installJazDependencies
``` 


### packJaz

Build a JAZ file using a config file informed as argument. Config example:

```json
{
  "dest": "build/my-package.jaz",
  "files": [
    "package.json", "lib/**", "routes/**", "controllers/**", "keys/**", "tests/**",
    "publicModules.js", "scripts/**", "startups/**"
  ],
  "ignore": [
      "lib/localConfig.js"
  ],
  "minifier": {
    "files": [
      "lib/**"
    ]
  },
  "e2c": [
    {
      "metadata": {
        "license": {
          "product": -1898148465
        }
      },
      "files": [
        "lib/protected-api/**"
      ]
    }
  ]  
}

```
 
Use the *minifier* option to minify and to obfuscate the files of the JAZ Package and 
the *e2c* option to encrypt files using the Engine E2C file format. Both features 
are experimental and not were officially released as supported product features. 

**Usage**: 

```sh
packJaz jaz.config.json
```