package.json

Directory Location

sample-integration/
└── package.json

Summary

The package.json file is identical to the package.json used in any NPM module. For detailed information about package.json files you can learn more about them from the official NPM registry website.

The package.json must be a valid JSON document, not just a javascript object literal. In particular this means that all keys must be double quoted and no comments are allowed in the file. Below, we cover the common fields that are used when specifying a package.json file for a Polarity integration.

Click here to view a sample package.json file

Properties

The following package.json properties are typically included in a Polarity integration package.json file.

name

required

The name is what your integration is called and along with the version field is required.

Some rules:

• The name must be less than or equal to 214 characters. This includes the scope for scoped packages.

• The name can't start with a dot or an underscore.

• The name must not have uppercase letters in it.

• The name could end up being part of a URL, an argument on the command line, and a folder name. Therefore, the name can't contain any non-URL-safe characters.

package.json

{
  "name": "GenericREST"
}

version

required

The name and version together form an identifier that is assumed to be completely unique. Anytime you make changes to your integration you should also make changes to the version number.

Versions must conform to the semver standard. Version numbers are split into three components <MAJOR>.<MINOR>.<PATCH>.

You should increment the MAJOR, MINOR, and PATCH values based on the following rules as taken from the semver.org website. Increment the,

• MAJOR version when you make incompatible API changes,

• MINOR version when you add functionality in a backwards-compatible manner, and

• PATCH version when you make backwards-compatible bug fixes.

When you first begin developing an integration it is customary to give it the version 0.1.0. Once you consider the integration "stable" you can mark the version to match the major version of the Polarity Server the integration is meant to run on. For example, if your integration is designed to work with version 3.x of Polarity server, the first release version of your integration should have the version number 3.0.0

package.json

{
  "version": "0.1.0"
}

You can mark an integration as being a beta by appending -beta to your version. For example, 3.0.0-beta

main

required

The main field is a module ID that is the primary entry point to your program. This should be a module ID relative to the root of your package folder. By convention, Polarity integrations specify this to be ./integration.js. For most Polarity integrations, the main script will contain the bulk of the logic and code required to build the integration.

package.json

{
"main": "./integration.js"
}

private

required

Should be set to true which will prevent your integration from accidentally being published to the public NPM registry.

package.json

{
"private": true
}

dependencies

optional

An object containing NPM module dependencies that should be installed alongside your integration. Since Polarity integrations are themselves node modules you can make use of any NPM modules to help with building your integration. For example, if you want to make REST requests you can use the request library to simplify the task. If you need to connect to a postgres database you could include the pg module.

package.json

{
  "dependencies": {
    "request": "2.76.0",
    "lodash": "4.16.6",
    "async": "2.1.2"
  }
}

Sample package.json

package.json

{
  "name": "GenericREST",
  "version": "1.0.0",
  "main": "./integration.js",
  "private": true,
  "dependencies": {
    "request": "^2.88",
    "lodash": "^4.17",
    "async": "^3.1"
  }
}