@axway/api-builder-project-utils

A set of utilities for API Builder and API Builder Plugins.

Getting started

To get started with API Builder plugin development, see @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:

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 and 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 step by step to copy a configuration file from your plugin on a postinstall:

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

Install the @axway/api-builder-project-utils module as shown above in the getting started.
Open your plugin's package.json file and verify the module was installed successfully as a dependency:

"dependencies": {
	...
	"@axway/api-builder-project-utils": ...
}

Inside of the package.json, add the newly created config folder to the files - they list what to be included with your package when it is installed as a dependency.

"files": [
	...
	"config",
],

Inside of the package.json, add a postinstall script that will use the api-builder-copy script.

"scripts": {
	...
	"postinstall": "api-builder-copy ./config/plugin.default.js ./conf/"
}

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 step by step to create a directory on postinstall:

Install the @axway/api-builder-project-utils module as shown above in the getting started.
Open your plugin's package.json file and verify the module was installed successfully as a dependency:

"dependencies": {
	...
	"@axway/api-builder-project-utils": ...
}

Inside of the package.json, add a postinstall script that will use the api-builder-create-directory script.

"scripts": {
	...
	"postinstall": "api-builder-create-directory ./my-directory"
}

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.