# @axway/api-builder-project-utils

> Utilities for API Builder projects

Latest version **3.0.0** (published 2022-09-09) · SEE LICENCE IN LICENSE license · 0 weekly downloads

## Install

```sh
npm install @axway/api-builder-project-utils
pnpm add @axway/api-builder-project-utils
yarn add @axway/api-builder-project-utils
bun add @axway/api-builder-project-utils
```

Provides the commands `api-builder-copy`, `api-builder-create-directory`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.0 |
| Published | 2022-09-09 |
| First published | 2020-06-17 |
| Weekly downloads | 0 |
| License | SEE LICENCE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 16 |
| Dependencies | 2 |
| Unpacked size | 21.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Axway |
| Maintainers | nkeranova, axway-npm, cb1kenobi, jamie.peabody, awam, bladedancer, axway_darnaudov, ddimonov-axway, neon-axway, vchauhan, mdimitrova, pdzhorev, axway_alasdair, pltod2, npetrovski-axway, pbozhkovaxway, mbonchev-axway, axway-vertex, cdobrica |
| Keywords | axway, amplify, api-builder, utils |

## Links

- npm: https://www.npmjs.com/package/@axway/api-builder-project-utils
- Homepage: https://platform.axway.com
- npm.io page: https://npm.io/package/@axway/api-builder-project-utils

## Dependencies (2)

- [chalk](https://npm.io/package/chalk.md) ^2.4.1
- [debug](https://npm.io/package/debug.md) ^4.3.1

## Recent versions

- 3.0.0 (latest) — 2022-09-09
- 2.0.1 (next) — 2021-10-08
- 2.0.0 (wrecsam) — 2021-09-23
- 1.0.3 (nashville) — 2021-05-20
- 1.0.2 (jaunpur) — 2021-03-24
- 1.0.1 (faro) — 2021-01-29
- 1.0.0 (qena) — 2020-06-17

## README

# @axway/api-builder-project-utils

A set of utilities for [API Builder](https://docs.axway.com/bundle/api-builder/page/docs/index.html) and [API Builder Plugins](https://docs.axway.com/bundle/api-builder/page/docs/developer_guide/plugins/index.html).

## Getting started
To get started with API Builder plugin development, see [@axway/api-builder-sdk](https://www.npmjs.com/package/@axway/api-builder-sdk). The template for new flow-node plugins does not include `@axway/api-builder-project-utils` by default. You need to install it manually:
```bash
npm install @axway/api-builder-project-utils
```

## Module contents
This module comes with two postinstall utilities to help you manage your plugins - [api-builder-copy](#api-builder-copy) and [api-builer-create-directory](#api-builer-create-directory).

### api-builder-copy
Copies a file from your plugin to the API Builder application directory. Nothing will be copied if the file already exists, or as part of a `--production` npm install.  For example, say you want to copy a configuration file from your plugin to the application directory. This script is intended to be used in a postinstall script, running after all the dependencies have been installed.

Usage:
```
api-builder-copy <source> <destination>
```

#### source
This is the path, relative to the plugin, to the file you want to copy. e.g. `./configs/plugin.default.js`.  The source cannot be a directory. Ensure that the file is included in `package.json` "files" when publishing your plugin and not ignored. The path should be posix style, e.g. `./conf/default.js`.

#### destination
The `destination` is relative to the target API Builder project and can point to a file or a directory. If the `destination` ends with a slash, e.g. `./conf/`, then the destination is regarded as a directory and if the directory does not exist, it is created before writing the `source` filename to the target directory. If `destination` does not end in a slash, then it is regarded as a file and will only copy the `source` file as the `destination` filename if the `destination` does not exist (e.g. as a file or directory). If `destination` does not end in a slash, but contains a relative directory, e.g. `./conf/banana.yaml`, then the directories will be recursively created before copying the `source` into a file named `banana.yaml`.

A destination containing multiple relative directories, e.g. `./conf/dir/banana.yaml` will only result in all missing directories being created when using Node.JS 10 or greater, so ensure your plugin documents a minimum Node.JS requirement of Node.JS 10 if doing this.

#### api-builder-copy example

Here is how you can use [api-builder-copy](#api-builder-copy) step by step to copy a configuration file from your plugin on a postinstall:

1. Create a directory - `/config` inside your plugin, and inside place your default configuration file - `plugin.default.js`. It is good habit to prefix your configuration with your plugin name, as if a configuration file with the same name exists at the targeted location, the copy script will not override and abort. For illustration purposes, lets take a look at what a newly scaffolded plugin looks like after the mentioned above change:
```
├───package.json
├───config/
│   ├───plugin.default.js
├───src/
│   ├───actions.js
│   ├───flow-nodes.yml
│   ├───icon.svg
│   ├───index.js
└───test/
    └───test.js
```
2. Install the `@axway/api-builder-project-utils` module as shown above in the [getting started](#getting-started).
3. Open your plugin's `package.json` file and verify the module was installed successfully as a dependency:
```
"dependencies": {
	...
	"@axway/api-builder-project-utils": ...
}
```
3. Inside of the `package.json`, add the newly created config folder to the [files](https://docs.npmjs.com/files/package.json#files) - they list what to be included with your package when it is installed as a dependency.
```
"files": [
	...
	"config",
],
```
4. Inside of the `package.json`, add a postinstall script that will use the [api-builder-copy](#api-builder-copy) script.
```
"scripts": {
	...
	"postinstall": "api-builder-copy ./config/plugin.default.js ./conf/"
}
```
5. This is it! Now, if you install your plugin into an API Builder application, after the npm install is complete, the postinstall will execute and copy your plugin's configuration into the desired location.
### api-builder-create-directory

Creates a new directory in an API Builder project. Nothing will be created if the directory already exists, or as part of a `--production` npm install.

Usage:
```
api-builder-create-directory <destination>
```

#### destination
This is the path, relative to the API Builder project, to the directory to create e.g. `./swagger`. If the directory does not exist the script will attempt to create the directory. 

A destination containing multiple relative directories, e.g. `./conf/dir` will only result in all missing directories being created when using Node.JS 10 or greater, so ensure your plugin documents a minimum Node.JS requirement of Node.JS 10 if doing this.

#### api-builder-create-directory example

Here is how you can use [api-builder-create-directory](#api-builder-create-directory) step by step to create a directory on postinstall:
1. Install the `@axway/api-builder-project-utils` module as shown above in the [getting started](#getting-started).
2. Open your plugin's `package.json` file and verify the module was installed successfully as a dependency:
```
"dependencies": {
	...
	"@axway/api-builder-project-utils": ...
}
```
3. Inside of the `package.json`, add a postinstall script that will use the [api-builder-create-directory](#api-builder-create-directory) script.
```
"scripts": {
	...
	"postinstall": "api-builder-create-directory ./my-directory"
}
```
4. This is it! Now, if you install your plugin into an API Builder project, after the npm install is complete, the postinstall will execute and the new directory will be created in the project.
## Changes

#### 3.0.0
- #6089: Breaking change: requires minimum Node.js version 16.x.

#### 2.0.0
- #7008: Breaking change: Providing a destination path without a trailing slash to `api-builder-copy` will now always result in the destination being treated as file, rather than being copied into an existing directory with the same name.
- #7008: Breaking change: Ensure that errors with `api-builder-copy` or `api-builder-create-directory` will not result in an `npm install` failing.
- #7008: Fixed inconsistency in behavior of `api-builder-copy` on Windows. Clarified documentation for accepted source and destination path formats.

#### 1.0.3
- #6815: Updated `debug` dependency.

#### 1.0.2
- #6772: Fixed the test cases failures due to the path issue in Windows OS.
- #6772: Fixed `getProjectPath` which was entirely broken on Windows.

#### 1.0.1
- #6601: Downgraded `chalk` to `2.4.1` to comply with minimum Node.js version 8.9.

#### 1.0.0
- #4567: Added `api-builder-copy` and `api-builder-create-directory` utility scripts to copy files and create directories in the target API Builder project on npm postinstall.

---
_Source: https://npm.io/package/@axway/api-builder-project-utils · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._