Changes to the Build Tools

With the v4 release, MathJax has switched to the pnpm package manager rather than npm. This speeds up installation and improves script handling. Although you can still use npm, some of the scripts in package.json call pnpm, so you will need to have pnpm installed to use those scripts. Fortunately, this only affects those who are compiling and packaging MathJax, so unless you are working with the MathJax source files, you should not be affected by this change. If you are only using MathJax in web pages via a CDN, for example, you will not need to worry about pnpm (or npm).

To install pnpm you can use

npm install -g pnpm

The tools used for creating the webpacked component files have been significantly updated for v4. Partly this is to accommodate the changes needed for the production of the dual MJS/CJS files, and partly in order to make it easier to do individual steps of the build process in isolation. There are now package scripts for performing most of the development tasks that you might need to do if you are modifying MathJax or building your own components.

In the past, to compile the typescript files into javascript, you would use pnpm -s compile, and to build the webpacked component files, you did pnpm -s make-components. These commands are still available, but there is a new

pnpm -s build

command that does both at once.

Because we now make both MJS and CJS versions of the MathJax files, there are commands to make each type. The commands above make the MJS versions, but there are also module-specific commands that make the MJS and CJS versions separately.

pnpm -s compile-cjs
pnpm -s compile-mjs

pnpm -s make-cjs-components
pnpm -s make-mjs-components

pnpm -s build-cjs
pnpm -s build-mjs

The generic versions are just aliases for the MJS-specific ones. Note that because the webpacked versions use the MJS JavaScript files, the make-cjs-components script is never run, but if you want to make ES5-based versions of the webpacked files,

pnpm -s compile-cjs
pnpm -s make-cjs-components

will create a bundle-cjs directory containing the ES5 webpacked files comparable to the ones that used to be in the es5 directory.

There is also

pnpm -s build-all

that does both the build-mjs and build-cjs actions, creating all the files in the mjs, cjs, bundle and components/cjs directories.

Because the make-components action webpacks all the components, a time consuming process, there is a make-one script that webpacks only one component. The format for this is

pnpm -s make-one <component> <module-type>

where <component> is the name of the directory in components/mjs that defines the component, and <module-type> is either mjs or cjs. For example

pnpm -s make-one input/tex mjs

would pack only the TeX input component.

These commands all rely on the components/bin/makeAll script, which has been enhanced for version 4. It now has a number of command-line options to control its functions, including:

  • --no-subdirs to prevent it from processing all the subdirectories of the given directory.

  • --cjs to process using CJS rules.

  • --mjs to process using MJS rules (the default).

  • --terse to only print the main headings rather than the file details like the files included in a webpacked version.

  • --build to only perform the build steps (i.e., creating the lib directories used for shared imports).

  • --copy to only perform the copy steps (e.g., copying the CHTML woff files into place).

  • --pack to only do the webpack steps.

  • --bundle-cjs to webpack into the bundle-cjs directory rather than the bundle directory.

These can also be passed to pnpm -s -- make-one if you want to restrict the steps performed (it already uses --no-subdirs and one of --cjs or --mjs).

These changes mean you only need to use makeAll, since it handles calling components/bin/build, components/bin/copy and components/bin/pack itself. The arguments for these sub-programs have changed in this version, particularly for components/bin/pack, so you should not call these by hand yourself unless you have looked at the internals of them carefully.