@axway/api-builder-project-utils
v3.0.0
Published
Utilities for API Builder projects
Downloads
313
Readme
@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
orapi-builder-create-directory
will not result in annpm 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
to2.4.1
to comply with minimum Node.js version 8.9.
1.0.0
- #4567: Added
api-builder-copy
andapi-builder-create-directory
utility scripts to copy files and create directories in the target API Builder project on npm postinstall.