# bb-bundle
Tools to automate creation of bundles.

## INSTALL

- Install library

```bash
npm install --global @bb-cli/bb-bundle
```



## USAGE

- Display help

```bash
bb-bundle --help
```

- Display version

```bash
bb-bundle --version
```

### COMMON OPTIONS:
- -f --format: Passing 'json' will cause the output to be JSON.
- -h --help: Show the help for the command.

### ENVIRONMENTS:
Set the following environment variables to change the output behaviour:

```bash
  LOG_LEVEL=silly|verbose|info|warn|error
  COLOR=false|true
```

## bb-bundle create
#### DESCRIPTION:

Creates bundle feature module and module loader configuration by concatenating and minifying project dependencies.

Bundle definitions can be created by bb-bundle define command.

#### EXAMPLES:

Creates bundle-bb-default and config-bb-module-loader modules inside ./bundle directory according to definition from ./bundle/def.json file:

```bash
  bb-bundle create bundle/def.json --output bundle
```

Create a bundle from multiple definition files:

```bash
  bb-bundle create bundle/portal1-bundle.json bundle/portal2-bundle.json --output bundle
```

Creates bundle modules inside ./bundle directory according to definition from ./bundle/def.json file and by using dependencies from provisioning package target/package.zip

```bash
  bb-bundle create bundle/def.json --output bundle --package-path target/package.zip
```

Creates my-bundles and config-bb-module-loader modules inside ./project-bundle directory according to definition from ./def.json file:

```bash
  bb-bundle create def.json --output project-bundle --bundle-module-name my-bundles
```
## bb-bundle define
#### DESCRIPTION:

Outputs bundle definition from the Backbase server for the given item.
Bundle definition can then be used as input for bb-bundle create command.

Defining your bundles can be a complicated process. There are many different ways
to optimize your bundling depending on how your portal/pages/widgets are
constructed.

Once you have created your bundle definition file/s, you can use `bb-bundle create`
to create the actual bundles.

These examples show some common use-cases for bundling your project:

#### EXAMPLES:

Scenario 1: Create bundles for each entire portal:

```
bb-bundle define --bundle-by portal --portal-name portal-a --output portal-a.json
```

Scenario 2: Create a bundle for every portal page:

```
bb-bundle define --bundle-by page --portal-name portal-a --output pages-bundles.json
```

Scenario 3: Create a bundle for specific pages:

```
# First create the page bundles:
bb-bundle define --bundle-by page --portal-name portal-a --page-names page-1,page-2 --output pages-bundles.json

# Create a fallback bundle for the rest of the portal
bb-bundle define --bundle-by portal --portal-name portal-a --exclude-pages page-1,page-2 --output portal-a.json
```

Scenario 4: Bundle per portal page, plus a common bundle for common widgets/features:

```
# First create a common bundle for the commonly used widgets/features:
bb-bundle define --bundle-by item --item-nameswidget-a,widget-b,feature-b --output common-bundle.json

# Create bundles for portal pages, excluding what's in the common-bundle.json
bb-bundle define --bundle-by page --portal-name portal-a --page-names page-1,page-2 --exclude-items widget-a,widget-b,feature-b \
  --output pages-bundle.json

# Create a fallback bundle for the rest of the portal
bb-bundle define --bundle-by portal --portal-name portal-a --exclude-pages page-1,page-2 --exclude-items widget-a,widget-b,feature-b \
  --output portal-a.json
```




## API
## Modules

<dl>
<dt><a href="#module_@bb-cli/bb-bundle">@bb-cli/bb-bundle</a> : <code>object</code></dt>
<dd><p>Main bb-bundle module.</p>
</dd>
</dl>

## Functions

<dl>
<dt><a href="#pageDependencies">pageDependencies(bbrest, portalName, excludeItems, pages)</a> ⇒ <code>BundleDefinition</code></dt>
<dd><p>Returns a bundle defintion for specific pages in the portal</p>
</dd>
<dt><a href="#allPageDependencies">allPageDependencies(bbrest, portalName, excludePages, excludeItems)</a> ⇒ <code>BundleDefinition</code></dt>
<dd><p>Returns a bundle defintion for every page in the portal</p>
</dd>
<dt><a href="#portalDependencies">portalDependencies(bbrest, portalName, excludePages, excludeItems)</a> ⇒ <code>Definition</code></dt>
<dd><p>Returns a single bundle defintion for an entire portal.</p>
</dd>
</dl>

<a name="module_@bb-cli/bb-bundle"></a>

## @bb-cli/bb-bundle : <code>object</code>
Main bb-bundle module.

**Example**  
Basic Example

```javascript
import { define, create } from '@bb-cli/bb-bundle';
```

* [@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle) : <code>object</code>
    * _static_
        * [.create(definitionPath, outputPath, options)](#module_@bb-cli/bb-bundle.create) ⇒ <code>Promise.&lt;BundleReport&gt;</code>
        * [.definePortalBundle(portalName, excludePages, excludeItems, options)](#module_@bb-cli/bb-bundle.definePortalBundle) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
        * [.definePageBundle(portalName, pageNames, excludePages, excludeItems, options)](#module_@bb-cli/bb-bundle.definePageBundle) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
        * [.defineItemBundle(itemNames, options)](#module_@bb-cli/bb-bundle.defineItemBundle) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
        * [.define(bundleBy, options)](#module_@bb-cli/bb-bundle.define) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
    * _inner_
        * [~BundleDefinition](#module_@bb-cli/bb-bundle..BundleDefinition) : <code>array.&lt;Definition&gt;</code>
        * [~Definition](#module_@bb-cli/bb-bundle..Definition) : <code>object</code>
        * [~BundleReport](#module_@bb-cli/bb-bundle..BundleReport) : <code>array.&lt;Report&gt;</code>
        * [~Report](#module_@bb-cli/bb-bundle..Report) : <code>object</code>

<a name="module_@bb-cli/bb-bundle.create"></a>

### @bb-cli/bb-bundle.create(definitionPath, outputPath, options) ⇒ <code>Promise.&lt;BundleReport&gt;</code>
Creates bundle definition file by parsing information retrieved from the server.

**Kind**: static method of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Returns**: <code>Promise.&lt;BundleReport&gt;</code> - Bundle report object.  

| Param | Type | Description |
| --- | --- | --- |
| definitionPath | <code>Array.&lt;string&gt;</code> | Path to bundle definition file. |
| outputPath | <code>string</code> | Path to output directory where modules will be created. |
| options | <code>Object</code> | Command options |
| options.bundleModuleName | <code>string</code> | Name of the bundle module to be created. |
| options.packagePath | <code>string</code> | Path of the provisioning package containing modules. |
| options.skipMinify | <code>boolean</code> | If set, bundles won't be minified. |
| options.force | <code>boolean</code> | If set, existing directories will be deleted. |
| options.protocol | <code>string</code> | Protocol of the URL identifying Backbase server |
| options.host | <code>string</code> | Host name of the URL identifying Backbase server |
| options.port | <code>string</code> | Port of the URL identifying Backbase server |
| options.context | <code>string</code> | Application context of the targeted Backbase server |
| options.username | <code>string</code> | Username |
| options.password | <code>string</code> | Password |
| options.authPath | <code>string</code> | authorization path |
| options.devmode | <code>string</code> | If set, will enable the enable-mocks and disable-bundles flags                                  in the module loader |

**Example**  
Basic example

```javascript
import { create } from '@bb-cli/bb-bundle'

create('./bundle/def.json', './bundle', { context: 'gateway' })
  .then(report => {
    console.log(report);
  })
  .catch(error => {
    handleError(error);
  });
```
<a name="module_@bb-cli/bb-bundle.definePortalBundle"></a>

### @bb-cli/bb-bundle.definePortalBundle(portalName, excludePages, excludeItems, options) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
Creates a portal bundle definition file.

This will define a single bundle for an entire portal.

**Kind**: static method of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Returns**: <code>Promise.&lt;BundleDefinition&gt;</code> - Bundle definition  

| Param | Type | Description |
| --- | --- | --- |
| portalName | <code>string</code> | Name of the portal (for bundling by portal or page) |
| excludePages | <code>Array.&lt;string&gt;</code> | Exclude these pages |
| excludeItems | <code>Array.&lt;string&gt;</code> | Exclude these items |
| options | <code>Object</code> | Command options |
| options.protocol | <code>string</code> | Protocol of the URL identifying Backbase server |
| options.host | <code>string</code> | Host name of the URL identifying Backbase server |
| options.port | <code>string</code> | Port of the URL identifying Backbase server |
| options.context | <code>string</code> | Application context of the targeted Backbase server |
| options.username | <code>string</code> | Username |
| options.password | <code>string</code> | Password |
| options.authPath | <code>string</code> | authorization path |

<a name="module_@bb-cli/bb-bundle.definePageBundle"></a>

### @bb-cli/bb-bundle.definePageBundle(portalName, pageNames, excludePages, excludeItems, options) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
Creates a bundle definition from portal pages.

This will create a bundle defintion for each page in a portal.

**Kind**: static method of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Returns**: <code>Promise.&lt;BundleDefinition&gt;</code> - Bundle definition  

| Param | Type | Description |
| --- | --- | --- |
| portalName | <code>string</code> | Name of the portal (for bundling by portal or page) |
| pageNames | <code>Array.&lt;string&gt;</code> | Page names when bundling by page |
| excludePages | <code>Array.&lt;string&gt;</code> | Exclude these pages |
| excludeItems | <code>Array.&lt;string&gt;</code> | Exclude these items |
| options | <code>Object</code> | Command options |
| options.protocol | <code>string</code> | Protocol of the URL identifying Backbase server |
| options.host | <code>string</code> | Host name of the URL identifying Backbase server |
| options.port | <code>string</code> | Port of the URL identifying Backbase server |
| options.context | <code>string</code> | Application context of the targeted Backbase server |
| options.username | <code>string</code> | Username |
| options.password | <code>string</code> | Password |
| options.authPath | <code>string</code> | authorization path |

<a name="module_@bb-cli/bb-bundle.defineItemBundle"></a>

### @bb-cli/bb-bundle.defineItemBundle(itemNames, options) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
Creates a bundle definition from portal a list of catalog items.

This will create a single defintion with all catalog items.

**Kind**: static method of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Returns**: <code>Promise.&lt;BundleDefinition&gt;</code> - Bundle definition  

| Param | Type | Description |
| --- | --- | --- |
| itemNames | <code>Array.&lt;string&gt;</code> | If bundling by item, only bundles these items |
| options | <code>Object</code> | Command options |
| options.protocol | <code>string</code> | Protocol of the URL identifying Backbase server |
| options.host | <code>string</code> | Host name of the URL identifying Backbase server |
| options.port | <code>string</code> | Port of the URL identifying Backbase server |
| options.context | <code>string</code> | Application context of the targeted Backbase server |
| options.username | <code>string</code> | Username |
| options.password | <code>string</code> | Password |
| options.authPath | <code>string</code> | authorization path |

<a name="module_@bb-cli/bb-bundle.define"></a>

### @bb-cli/bb-bundle.define(bundleBy, options) ⇒ <code>Promise.&lt;BundleDefinition&gt;</code>
Create a bundle definition file.

There are 3 possible bundling strategies. Depending which strategy is used different
options may apply.

**Kind**: static method of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Returns**: <code>Promise.&lt;BundleDefinition&gt;</code> - Bundle definition  

| Param | Type | Description |
| --- | --- | --- |
| bundleBy | <code>[BUNDLE_BY](#BUNDLE_BY)</code> | The bundling strategy to use |
| options | <code>Object</code> | Command options |
| options.portalName | <code>string</code> | Name of the portal (for bundling by portal or page) |
| options.pageNames | <code>Array.&lt;string&gt;</code> | Page names when bundling by page |
| options.excludePages | <code>Array.&lt;string&gt;</code> | If bundling by portal, exclude these pages |
| options.itemNames | <code>Array.&lt;string&gt;</code> | If bundling by item, only bundles these items |
| options.excludeItems | <code>Array.&lt;string&gt;</code> | If bundling by portal or page, exclude these items |
| options.protocol | <code>string</code> | Protocol of the URL identifying Backbase server |
| options.host | <code>string</code> | Host name of the URL identifying Backbase server |
| options.port | <code>string</code> | Port of the URL identifying Backbase server |
| options.context | <code>string</code> | Application context of the targeted Backbase server |
| options.username | <code>string</code> | Username |
| options.password | <code>string</code> | Password |
| options.authPath | <code>string</code> | authorization path |

**Example**  
Basic example, bundling by page:

```javascript
import { define, BUNDLE_BY } from '@bb-cli/bb-bundle'

// Just create a single page bundle for page-my-page
const pageNames = ['page-my-page'];
define(BUNDLE_BY.PAGE, { pageNames, port: '8080' })
  .then(bundleDef => {
    console.log(bundleDef);
  });
```
<a name="module_@bb-cli/bb-bundle..BundleDefinition"></a>

### @bb-cli/bb-bundle~BundleDefinition : <code>array.&lt;Definition&gt;</code>
Collection of the bundle definition objects.

**Kind**: inner typedef of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
<a name="module_@bb-cli/bb-bundle..Definition"></a>

### @bb-cli/bb-bundle~Definition : <code>object</code>
Bundle definition object. Describes content and context of the bundled file.

**Kind**: inner typedef of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| portal | <code>string</code> | Name of the portal |
| page | <code>string</code> | Name of the page |
| path | <code>string</code> | Relative path of the bundle file |
| dependencies | <code>array.&lt;string&gt;</code> | Names of dependencies |

<a name="module_@bb-cli/bb-bundle..BundleReport"></a>

### @bb-cli/bb-bundle~BundleReport : <code>array.&lt;Report&gt;</code>
Collection of Report objects.

**Kind**: inner typedef of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
<a name="module_@bb-cli/bb-bundle..Report"></a>

### @bb-cli/bb-bundle~Report : <code>object</code>
Report object. Describes created bundle file.

**Kind**: inner typedef of <code>[@bb-cli/bb-bundle](#module_@bb-cli/bb-bundle)</code>  
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| portal | <code>string</code> | Name of the portal |
| page | <code>string</code> | Name of the page |
| path | <code>string</code> | Relative path of the bundled file |
| size | <code>string</code> | Size of the bundled file in kilobytes |

<a name="BUNDLE_BY"></a>

## BUNDLE_BY : <code>enum</code>
**Kind**: global enum  
**Properties**

| Name | Type | Default |
| --- | --- | --- |
| PORTAL | <code>String</code> | <code>portal</code> | 
| PAGE | <code>String</code> | <code>page</code> | 
| ITEM | <code>String</code> | <code>item</code> | 

<a name="pageDependencies"></a>

## pageDependencies(bbrest, portalName, excludeItems, pages) ⇒ <code>BundleDefinition</code>
Returns a bundle defintion for specific pages in the portal

**Kind**: global function  

| Param | Type | Description |
| --- | --- | --- |
| bbrest | <code>BBRestClient</code> | Rest client to connect to portal |
| portalName | <code>string</code> | Name of portal |
| excludeItems | <code>Array.&lt;string&gt;</code> | Array of items to exclude.  All dependencies of items will be excluded too. |
| pages | <code>Array.&lt;string&gt;</code> | Array of page names to create bundles for |

<a name="allPageDependencies"></a>

## allPageDependencies(bbrest, portalName, excludePages, excludeItems) ⇒ <code>BundleDefinition</code>
Returns a bundle defintion for every page in the portal

**Kind**: global function  

| Param | Type | Description |
| --- | --- | --- |
| bbrest | <code>BBRestClient</code> | Rest client to connect to portal |
| portalName | <code>string</code> | Name of portal |
| excludePages | <code>Array.&lt;string&gt;</code> | Array of pages to exclude.  All items and dependencies from the pages will be excluded. |
| excludeItems | <code>Array.&lt;string&gt;</code> | Array of items to exclude.  All dependencies of items will be excldued too. |

<a name="portalDependencies"></a>

## portalDependencies(bbrest, portalName, excludePages, excludeItems) ⇒ <code>Definition</code>
Returns a single bundle defintion for an entire portal.

**Kind**: global function  

| Param | Type | Description |
| --- | --- | --- |
| bbrest | <code>BBRestClient</code> | Rest client to connect to portal |
| portalName | <code>string</code> | Name of portal |
| excludePages | <code>Array.&lt;string&gt;</code> | Array of pages to exclude.  All items and dependencies from the pages will be excluded. |
| excludeItems | <code>Array.&lt;string&gt;</code> | Array of items to exclude.  All dependencies of items will be excldued too. |

