# Pentaho web package

Pentaho detects and manages [OSGi](https://www.osgi.org/) bundles that contain Pentaho web packages, collecting the information needed to build the AMD/RequireJS configuration and to set up the mappings needed to serve the package resources through HTTP. A package is described by a `package.json` file, based upon the [package.json spec](https://docs.npmjs.com/files/package.json) and is mostly compatible with files generated by the [npm](https://www.npmjs.com/) tool.

You create a web package to define your configurations and mappings through the following supported fields:

* `name` and `version`
* `paths`
* `dependencies`
* `config`

## The name and version fields

You must specify the `name` and `version` fields. These fields are the most important in the `package.json` file. The package will not install without these fields.

These fields must adhere to the following rules:

* The `name` must be shorter than 214 characters, including the scope, for scoped packages.
* The `name` cannot start with a dot or an underscore.
* The `name` should not have uppercase letters.
* The `name` will end up being part of an URL. You must avoid any non-URL-safe characters, except forward-slashes (`/`) are permitted.
* The `version` must follow the Semantic Versioning Specification (<http://semver.org/>).

The `name` and `version` fields together form a unique system identifier for the package. This unique system identifier is used internally as the base AMD/RequireJS module identifier and as part of the HTTP location where the resources are served.

### Example

The following lines of code are an example of specifying the mandatory `name` and `version` fields:

```json
{
  "name": "my-viz-lib",
  "version": "1.0.0"
}

```

You can specify an organization in the `name` field, as shown in the following sample lines of code:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0"
}

```

## The paths field

You can use the `paths` field to expose the resources of a given package path under a base module identifier.

If you do not specify a value for the `paths` field, the package name is used to map the package’s root path, as if, you specified the package name for the path, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "@my-org/viz-lib": "/"
  }
}

```

You would normally specify scoped and hyphenated package name, yet the AMD module identifiers are also valid JavaScript identifiers. For this case, you would explicitly specify a root module, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib",
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  }
}

```

## The dependencies field

You can use the `dependencies` field to map a package name to a version range in a simple object. The version range is a string that has one or more space-separated descriptors, as shown in the following example:

```json
{
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "dependencies": { 
    "bar": "~2.0" 
  }
}

```

See <https://github.com/npm/node-semver#ranges> for the definitions of available space-separated descriptors.

The `dependencies` field is used by Pentaho to determine the dependency tree, resolve runtime dependencies, and build the proper AMD/RequireJS mappings to allow each package to request external modules that satisfy the dependencies’ version restrictions.

For instance, in the above example, the code in the `@my-org/viz-lib` package can use modules from the `bar` dependency without the knowledge that it is available at a path such as `/bar@2.1.4/foo`.

### Unsupported identifiers

Only version ranges are supported. You cannot use the following identifiers:

* Local paths
* URLs
* Git URLs
* GitHub short URLs

## The config field

You set the `config` field to the module identifier listed your configuration object that is made available to AMD/RequireJS modules that match. Modules with a matching identifier can access the configuration object via `module.config`. You use this object to configure the `pentaho/modules` module, which is a basic inversion-of-control mechanism to inject the package resources into the system.

For example, to declare that the JavaScript module package in `config.js` exports a value that is an instance of the `pentaho/config/spec/IRuleSet` type, you would use the following sample lines of code:

```json
{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/config": {"type": "pentaho/config/spec/IRuleSet"}
    }
  }
}

```

You can also use the `config` field to declare that a type (such as that exported by the JavaScript module in `Model.js`) is a subtype of the visualization base type, `pentaho/visual/Model`, as shown in the following example:

```json
{ 
  "name": "@my-org/viz-lib", 
  "version": "1.0.0",
  "paths": {
    "myOrg/visual": "/"
  },
  "config": {
    "pentaho/modules": {
      "myOrg/visual/Model": {"base": "pentaho/visual/Model"}
    }
  }
}

```