A plain-English guide to words that come up whenever FreeITSM adds or updates a library: dependency, npm, bundle, module, vendoring. It was written when PDF exports moved from jsPDF to PDFKit (#254), because that was the first library FreeITSM took that is a module rather than a plain script - but it applies to every library in the repository.

No knowledge of JavaScript tooling is assumed.

• Why PDFKit: PDF exports moved to PDFKit
• How FreeITSM's PDF code works: PDF writer - Developer Guide

Nobody writes everything. To make PDFs, FreeITSM uses PDFKit, a library other people wrote and maintain. FreeITSM depends on it, so PDFKit is a dependency.

Dependencies have dependencies of their own. PDFKit uses:

So "add PDFKit" really means "add PDFKit and about fifteen packages it stands on". That chain is the dependency tree.

Most JavaScript libraries are published on npm (npmjs.com) - think of it as a public warehouse. Each library is a package, with a name (pdfkit), versions (0.20.2), and a list of the packages it needs.

Most JavaScript projects never copy libraries by hand. They keep a list (package.json) and a tool (npm install) fetches the whole tree from the warehouse. A second tool - a bundler - then joins it all into files a browser can load.

FreeITSM does neither, on purpose. There is no package.json, no npm install, no build step. Installing FreeITSM is: copy the files, point a web server at them, done. That is a big part of why it runs on shared hosting, on Windows with WAMP, and on servers with no internet. The price is that libraries must be prepared once, by hand, and kept in the repository. That is vendoring.

Vendoring means copying a library's files into your own repository and shipping them with your code, instead of fetching them from somewhere else when the app runs.

FreeITSM vendors everything: TinyMCE, Chart.js, pdf.js, Prism - and now PDFKit and the Noto fonts. They live under assets/js/vendor/ and assets/fonts/.

What that buys:

What it costs:

• The repository is bigger. The PDF fonts are about 10 MB.
• Updates are manual. No tool warns that a newer version exists - which is why VENDOR.md lists every vendored library, its version and where it came from, and checking it is part of every release.
• Security scanners cannot see it. Tools that read package.json find nothing and report "no dependencies". VENDOR.md is how a person can still check.

Air-gapped installs: because everything is vendored, a FreeITSM server with no internet at all makes PDFs exactly as one with internet does. The PDF writer's test checks it: every file the browser loaded must come from the FreeITSM server itself.

This is the part that changed with PDFKit.

<script src="assets/js/vendor/chart.umd.min.js"></script>

The file runs and leaves its library on the page as a global - for example window.Chart. Any later script just uses Chart. Simple, and how FreeITSM loaded jsPDF (window.jspdf). Libraries built for this are often called UMD builds.

A module is a JavaScript file that says exactly what it needs and what it offers:

import { create } from 'fontkit';          // what it needs
export { PDFDocument, registerFile };      // what it offers

Nothing leaks onto window. Whoever wants the library asks for it by name. Modules are tidier, and most libraries are now published only this way - PDFKit's browser version among them. There is no window.PDFDocument file to drop into a <script> tag.

import { create } from 'fontkit' is a name, not a file. A bundler or npm knows where fontkit lives; a browser does not. So PDFKit's own module file, loaded as it is, fails at the first import.

A bundle is one file containing a library and its whole dependency tree, with every import already resolved inside it. Nothing is left to look up.

FreeITSM's PDFKit is exactly that: assets/js/vendor/pdfkit/pdfkit.bundle.js, about 550 KB. It was made once by esm.sh, a public service that builds such bundles from npm packages, downloaded from:

https://esm.sh/[email protected]/es2020/pdfkit.bundle.mjs

and committed. esm.sh was used once, to build the file - FreeITSM never contacts it while running.

Two details:

• Renamed .mjs to .js. .mjs means "module", but IIS and older nginx do not know the extension and serve it with the wrong type, which a browser refuses to run. A browser decides whether a file is a module from how it is loaded, not from its name, so .js is safe. pdf.js in FreeITSM was renamed for the same reason.
• It is checked to be self-contained. If the bundle still imported anything from a URL, an air-gapped install would break. The update steps (section 6) include checking that.

FreeITSM's own code is plain scripts. A plain script can still load a module, with import() - a function that fetches a module and gives back what it exports:

const lib = await import('/freeitsm/assets/js/vendor/pdfkit/pdfkit.bundle.js');
const doc = new lib.PDFDocument();

That is what assets/js/pdf-writer.js does, the first time somebody makes a PDF. Pages only include the writer, as a plain script; PDFKit is fetched only when it is actually needed, so a page where nobody exports a PDF never loads it.

Copying someone's code into your repository is only allowed if its licence says so. Licences fall into two families:

FreeITSM is MIT. Everything in the PDFKit bundle is MIT, except one tiny helper under Apache 2.0 - both permissive. The fonts are under the SIL Open Font License, which exists for bundling fonts with software (the only real rule: the fonts may not be sold on their own). So:

• assets/js/vendor/pdfkit/LICENSE.txt lists every package inside the bundle with its copyright line, and the licence texts.
• Each font folder has its OFL.txt.

Checked when PDFKit was chosen: PDF exports moved to PDFKit - licensing.

Because PDFKit is a bundle of many packages, updating it is not "replace one file":

1. Find the new version: curl -s https://registry.npmjs.org/pdfkit/latest - read version, and read dependencies for anything new.
2. Check every licence is still permissive: for each dependency, curl -s https://registry.npmjs.org/<name>/latest and read license. A copyleft one is a stop.
3. Download the bundle: https://esm.sh/pdfkit@<version>/es2020/pdfkit.bundle.mjs.
4. Check it is the version you asked for (its first line is /* esm.sh - pdfkit@<version> */) and self-contained - search it for import( or from " pointing at a URL; there must be none.
5. Save it as assets/js/vendor/pdfkit/pdfkit.bundle.js, and update LICENSE.txt and the row in VENDOR.md.
6. Test: php tests/pdf-writer.php (20 checks), then open the PDF it saves and look - Polish, Hindi, Tamil and Bengali, a table over three pages. Then php tests/security-findings/run.php (section F6 checks the version matches VENDOR.md).
7. Bump the writer's ?v= on the pages so browsers fetch it fresh, and export a PDF from Knowledge and from a Report Pack by hand.

TRAP: line endings. The bundle is minified but has line breaks inside its strings. Git on Windows (core.autocrlf) converts line endings on checkout, which would change what PDFKit writes into PDFs. .gitattributes marks the file -text - never convert - so every checkout gets the exact bytes that were tested. Keep that line when the file is replaced, and check with git show HEAD:assets/js/vendor/pdfkit/pdfkit.bundle.js | cmp - <the download>.

TRAP: assets/js/pdf-writer.js reads one PDFKit internal (_font.font, to ask whether a font has a character). A PDFKit update could rename it. If it does, the writer stops noticing missing characters and they show as empty boxes - the "colon in Bengali" and "।" checks in tests/pdf-writer.php catch that.

• PDF exports moved to PDFKit · PDF writer - Developer Guide
• Offline and air-gapped installs
• VENDOR.md - every vendored library