npm package: @rio-cloud/vite-plugin-frontend-license-check
Description: Makes consistent license checking and reporting easier
Author: TB Digital Services GmbH
Latest version: 3.0.0

# License Checking for RIO Frontends

## Why 🤷

**You need to check the licenses of all third party dependencies your project is bundling (a.k.a. shipping, a.k.a.
re-distributing).**

This package contains the code that is needed to do just that. It homogenizes boilerplate code that would otherwise be
copied & pasted from project to project (and is virtually impossible to keep aligned and maintained everywhere 
consistently).

## What ⁉️

This Vite plugin will
- check the licenses of all dependencies that get bundled into your output
- if any dependencies' licenses are not covered by the whitelist, the build will fail
- generate a `libraries.json` report in your build's output directory
- generate a `libraries.html` in your build's output directory (unless you have something in your build config that
  conflicts with it, **or** you explicitly disable this feature using the `skipLibrariesPageGeneration` flag)

The license whitelist will have to be provided as a file named `frontend-license-whitelist.json` in the root of your
project. It makes sense to put that path in your `.gitignore` file! Please make sure to download the appropriate license
whitelist **before** you run `npm run build` in your pipeline!

Take a look at the structure of [the dummy whitelist](dummy-project/frontend-license-whitelist.json). It contains the
SPDX-compliant license identifiers plus a fallback list of strings to match. For your *actual* project builds, make sure
to read the [blog post](https://confluence.collaboration-man.com/spaces/MAN/blog/2025/12/08/367347512/OSS+license+checking+for+frontends)
detailing how to obtain the official whitelist from the Security Guild in your project's build pipeline.

By default, the plugin will not do anything when you `npm run build` locally. You can, however, force the license
checker for local builds by setting the `RIO_LICENSE_CHECK` environment variable to `1`:

```shell
RIO_LICENSE_CHECK=1 npm run build
```

## How 🤔

For the license check and report generation, we rely on the mighty
[rollup-plugin-license](https://www.npmjs.com/package/rollup-plugin-license) and inject our config into it.

The "Libraries App" gets created into your output. So when you're building https://foo.bar.example, you can navigate to
https://foo.bar.example/libraries.html to see the app.

You can even add a comma-separated list of additional frontend root URLs to your `.env.production` file. Those will get
picked up by the app automatically so that it can aggregate dependencies from multiple frontend projects (not at build
time, but when you're visiting the app). Example:

```
VITE_INCLUDED_RIO_IFRAME_ORIGINS=https://blah.fasel.suelz,https://wurst.kaese/schwafel
```

With this config, the app will attempt to load https://blah.fasel.suelz/libraries.json and 
https://wurst.kaese/schwafel/libraries.json on load. If something goes wrong there, a notification is shown. A similar
`console.error` log is also created, so if you have alerting set up for that, you'll see that right away.

## Shut up and take my money 💰

Add this package in your `devDependencies`:

```shell
npm install --save-dev @rio-cloud/vite-plugin-frontend-license-check 
```

Add the Vite plugin into your frontend's Vite build:

```typescript
import { rioLicenseCheck } from '@rio-cloud/vite-plugin-frontend-license-check';
import react from '@vitejs/plugin-react';
import { visualizer } from 'rollup-plugin-visualizer';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [react(), rioLicenseCheck()],
    // ...
});
```

By default, the plugin will use the license whitelist which is provided by our Security Guild (see above). However, you
can provide either a list of SPDX-compliant license identifiers and/or a list of fallback license strings to the plugin,
to **narrow** the applied list(s). The **intersection** of the standard and your provided information will be used. 

👉You can never "break out" of the RIO standard, but you can decide to be stricter regarding which licenses are okay for
your bundled dependencies.

## 🔥 Open issues / compatibility notes

Note that this plugin **will not work** with Vite below version `7.1` and/or with React 17 / 19! The `peerDependencies`
are set appropriately, but you know - npm and stuff...

Setting the environment variable on Windows / PowerShell is most likely **not** going to work with the simple one-liner
above. It's recommended to prepare a npm script in your project combined with
[cross-env](https://www.npmjs.com/package/cross-env), for example:

```json
{
  "scripts": {
    "build": "vite",
    "build-local-with-license-check": "cross-env RIO_LICENSE_CHECK=1 npm run build"
  }
}
```