npm package: @studyportals/bob-manifest-generator
Description: A Webpack plugin that generates a manifest file for your microservice.
Author: Frank Kluijtmans
Latest version: 5.1.0

# BobManifestGenerator

BobManifestGenerator is a `Webpack` plugin that helps you generate a `manifest.json` file for your microservice, which can then be loaded via [Bob](https://github.com/studyportals/BOB).

## Table of Contents
- [Prerequisites](#prerequisites)
- [Plugins](#plugins)
  - [ManifestGenerator](#manifestgenerator)
     - [Output](#output)
     - [Options](#options)
  - [DllReferencePlugin](#dllreferenceplugin)
     - [Output](#output)
     - [Options](#options)
  - [DllManifestGenerator](#dllmanifestgenerator)
     - [Output](#output)
     - [Options](#options)

## Prerequisites

In order to use BobManifestGenerator you need the following Prerequisites:

- `webpack` version `5` or higher
- `node.js` version `10.13.0` or higher
- `npm` version `6.4.1` or higher

## Plugins

In order to start using the plugins you should first install the package from `npm`:

```bash
npm i -D @studyportals/bob-manifest-generator
```

After installing it you can import it to your webpack configuration file like so:

```javascript
const BobManifestGenerator = require('@studyportals/bob-manifest-generator');
```

BobManifestGenerator provides 3 different plugins for you to use. Here you can see how to use all 3 of them.

### ManifestGenerator

ManifestGenerator takes care of building a manifest file for your microservice that is readable by Bob. You can use it like so:

```typescript
plugins: [
  new BobManifestGenerator.ManifestGenerator({
      name: string,
      html: string,
      embedChunk: string,
      baseURL: string,
      crossorigin: boolean,
      exclude: string[],
      async: string[],
      defer: string[],
      priority: boolean
  })
]
```

#### Output

ManifestGenerator outputs a manifest file with the following structure:

```javascript
{
    "name": "Dummy Microservice",
    "html": "https://bucket.prtl.co/index.html",
    "crossorigin": true,
    "assets": {
        "js": [
            {
                "url": "https://bucket.prtl.co/dist/bundle.[hash].js",
                "async": true
            }
        ],
        "css": [
            {
                "url": "https://bucket.prtl.co/dist/styles.[hash].css",
                "defer": false
            }
        ]
    },
    "dllDependencies": [
		{
			"name": "[PACKAGE-NAME]-dll",
            "version": "1.0.0",
            "assets": {
                "js": [
                    {
                        "url": "script.js"
                    }
                ],
                "css": [
                    {
                        "url": "style.css"
                    }
                ]
            }
		}
	]
}
```

#### Options

When using the plugin, you can pass an options object to the constructor. This can include the following options:

| Option | Description | Required |
|---|---|---|
| `name` | The name of your microservice. | yes |
| `html` | The HTML that should be injected on the page the microservice is loaded in. | no |
| `embedChunk` | The name of the chunk that should be injected into the manifest html. This should only be used as a **last resort** where javascript need's be injected inline. Please **discuss** this within the Frontend tribe before implementation. | no |
| `baseURL` | The base URL for your microservice's assets. This will be prepended to the filenames. | no (default: `''`) |
| `crossorigin` | Determines if JS assets will be inserted on the page with a `crossorigin="anonymous"` tag. | no (default: `true`) |
| `exclude` | An array of filenames to be excluded from the manifest. This can be just a filename or a filename including extension. When `true` is passed as a value, all assets will be excluded. | no (default: `[]`) |
| `async` | An array of JS filenames to be loaded async. This can be just a filename or a filename including extension. Keep in mind that only javascript assets may be loaded async. When `true` is passed as a value, all javascript assets will be loaded async. | no (default: `[]`) |
| `defer` | An array of CSS filenames to be lazy-loaded. This can be just a filename or a filename including extension. Keep in mind that only CSS assets may be lazy-loaded. When `true` is passed as a value, or when the value is omitted, all CSS assets will be lazy-loaded.| no (default: `[]`) |
| `priority` | Whenever a microservice should be loaded with priority or not. This is usually the case when other microservices depend on your priority microservice. Such as StudentJS and AnonymousStudent | no (default: `false`) |

**IMPORTANT: Assets that are generated from dynamic imports will be automatically excluded from the manifest and therefore don't need to be excluded using the `exclude` option.**

### DllReferencePlugin

DllReferencePlugin can be used to create references to dependencies you want to use via DLL (Dynamic Library Linking). Bob will then take care of de-duplicating these dependencies when they are used by multiple microservices.

```typescript
plugins: [
  new BobManifestGenerator.DllReferencePlugin({
      name: string,
      manifest: object
  })
]
```

#### Output

DllReferencePlugin will add references to DLL dependencies to your manifest file like so:

```javascript
{
    "dllDependencies": [
		{
			"name": "[PACKAGE-NAME]-dll",
            "version": "1.0.0",
            "assets": {
                "js": [
                    {
                        "url": "script.js"
                    }
                ],
                "css": [
                    {
                        "url": "style.css"
                    }
                ]
            }
		}
	]
}
```

#### Options

When using the plugin, you can pass an options object to the constructor. This can include the following options:

| Option | Description | Required |
|---|---|---|
| `name` | The name of the package without the `@studyportals/` portion. | yes |
| `manifest` | The manifest JSON that was generated by the DLL package you want to add as a dependency. | yes |

### DllManifestGenerator

DllManifestGenerator can be used inside DLL bundle packages to create a manifest for it.

```typescript
plugins: [
  new BobManifestGenerator.DllManifestGenerator()
]
```

When implementing DllManifestGenerator, keep the following in mind:

- All assets should be used from a `dist` folder in the root of your DLL package.
- If you want to add a stylesheet to your DLL bundle's assets you'll have to add the filename for it in the `style` property of your DLL package `package.json` file.

```json
{
    "style": "style.css"
}
```

#### Output

DllManifestGenerator will gather all necessary information about the DLL bundle in a manifest file:

```javascript
{
    "name": "[PACKAGE-NAME]-dll",
    "version": "1.0.0",
    "assets": {
        "js": [
            {
                "url": "script.js"
            }
        ],
        "css": [
            {
                "url": "style.css"
            }
        ]
    }
}
```