@city-of-helsinki/license-notices weekly downloads statistics

@city-of-helsinki/license-notices

Writes the license notices of every third-party package bundled into the production build of a Vite, Next.js, webpack or Rsbuild application, and serves them from the root of the deployed application.

Why

Serving an application to a browser distributes its JavaScript bundle, and with it every open source package the bundle contains. Almost every open source license attaches conditions to that distribution:

• MIT, ISC, BSD and Apache-2.0 require the copyright notice and the license text to travel with the code.
• MPL-2.0 (section 3.2) also requires telling recipients where the source of the MPL-covered files can be obtained.
• GPL-2.0 requires a copy of the license (section 1) and access to the complete corresponding source (section 3).

A minified bundle carries none of this: minification strips the license comments, and the license files stay behind in node_modules. This package collects them at build time from exactly the packages that ended up in the bundle, and writes them next to it:

• third-party-licenses.txt, the notices for people to read, and
• oss-licenses.json, the same data for license audit tooling.

Both are generated on every build, so they always describe the build they ship with. Neither is committed to the repository.

It prefers failing the build to shipping something nobody has checked: a license it cannot identify, a license decision that no longer matches the package, or a copyleft license it has no notice rules for all stop the build with a message that says what to check. See When the build fails.

Setup

1. Add the package:

   pnpm add --save-dev @city-of-helsinki/license-notices
   

2. Put everything specific to the repository in a config file of its own. For Vite, for example scripts/thirdPartyLicenses.config.ts:

   import type { ThirdPartyLicensesConfig } from '@city-of-helsinki/license-notices';
   
   export const thirdPartyLicensesConfig: ThirdPartyLicensesConfig = {
     repositoryUrl: 'https://github.com/City-of-Helsinki/<repository>',
   };
   

   For Rsbuild, the same file, with the type imported from @city-of-helsinki/license-notices/rsbuild.

   A CommonJS next.config.js cannot load a TypeScript file, so for Next, for example scripts/thirdPartyLicenses.config.js, typed with JSDoc:

   /** @type {import('@city-of-helsinki/license-notices/next').ThirdPartyLicensesConfig} */
   const thirdPartyLicensesConfig = {
     repositoryUrl: 'https://github.com/City-of-Helsinki/<repository>',
   };
   
   module.exports = { thirdPartyLicensesConfig };
   

3. Add it to the build, see Vite, Next.js or webpack below.

4. Make sure the application's own LICENSE file is present when the build runs, because the notices start with the application's own license. In a Docker build, do not exclude it in .dockerignore, and if .dockerignore lists the files to include instead, add !LICENSE. A Dockerfile that copies the files it needs one by one has to name it as well:

   COPY --chown=default:root index.html LICENSE vite.config.ts ./
   

   One that copies the whole build context, with COPY . ., needs nothing more.

5. Run pnpm build and read the output. The first build of an existing application usually needs a license decision or two; the build tells which.

6. Consider a test for the license decisions in the config, since a reader cannot verify them from the bundle:

   it('elects Apache-2.0 for the dual-licensed dompurify', () => {
     expect(thirdPartyLicensesConfig.licenseDecisions?.dompurify?.license).toBe(
       'Apache-2.0'
     );
   });
   

Vite

Add the plugin to vite.config.ts:

import { thirdPartyLicenses } from '@city-of-helsinki/license-notices';

import { thirdPartyLicensesConfig } from './scripts/thirdPartyLicenses.config';

export default defineConfig({
  plugins: [
    // ...
    thirdPartyLicenses(thirdPartyLicensesConfig),
  ],
});

The plugin only runs in vite build, and emits both files into the build output.

Next.js

Wrap the Next config with withThirdPartyLicenses, from the @city-of-helsinki/license-notices/next entry point, and enable production source maps, which the notices are read from:

const {
  withThirdPartyLicenses,
} = require('@city-of-helsinki/license-notices/next');

const {
  thirdPartyLicensesConfig,
} = require('./scripts/thirdPartyLicenses.config');

module.exports = {
  // ...
  productionBrowserSourceMaps: true,
};

module.exports = withThirdPartyLicenses(
  module.exports,
  thirdPartyLicensesConfig
);
module.exports = withSentryConfig(module.exports, {
  // ...
});

• The notices are written during next build, after the client is compiled, into the public directory. next start serves them from there, and so does the server of an output: 'standalone' build, once public is copied next to it as Next's deployment instructions say. Add both files to .gitignore:

  /public/third-party-licenses.txt
  /public/oss-licenses.json
  

  Each build replaces the files it writes, but leaves a file it no longer writes in place, after manifestFileName is set to false or a file name is changed. Remove such a file by hand.…