.. _node-preload:

############################## Using Components Synchronously ##############################

MathJax components are designed to operate in a browser environment, where loading components is inherently asynchronous as the browser has to wait for files to be downloaded over the network. This means that using MathJax's promise-based typesetting and conversion functions is generally required, and so the rest of your code needs to be designed to handle the promises that are part of MathJax. That can complicate your code, and your work with other frameworks may require you to operate synchronously.

In a node application, you can load components individually yourself via node's import or require() commands, rather than relying on MathJax's :ref:loader-component, which operates asynchronously. With a little care, this can give you the ability to work with MathJax synchronously (i.e., without the need to use promises). It also gives you more complete control over the loading of components, though in this case you do need to handle loading dependencies yourself, and make sure the components are loaded in the right order.

This approach lets you take advantage of using the convenient packaging of MathJax into individual components, the configuration of MathJax through the global :js:data:MathJax variable, and its automatic creation of objects and methods by the :ref:startup-component component, while still allowing you to work completely synchronously with the MathJax code.

Note, however, that this means you will not be able to use the \require macro in TeX expressions, and that TeX extensions will not be able to be auto-loaded, as those actions are asynchronous.

.. warning::

In MathJax v4, with the introduction of new fonts that include many more characters than the original MathJax TeX fonts did, the fonts have been broken into smaller pieces so that your readers don't have to download the entire font and its data for characters that may never be used. That means that typesetting mathematics may need to operate asynchronously even if the TeX doesn't include \require or any auto-loaded extensions, as the output itself could need extra font data files to be loaded. Thus in version 4, it is always best to use the promise-based commands, when possible.

The examples below show how to pre-load the needed font data so that you can still work synchronously even with the larger v4 fonts.

.. _preload-basics:

The Basics of Pre-Loading Extensions

First, :ref:get a copy of the MathJax code library <obtain-mathjax>. Here, we will assume you have used npm or pnpm to install the @mathjax/src@4 package. You will need to use @mathjax/src, not just mathjax, since the examples given here rely on access to the component definitions and other source code that is not part of the mathjax package, which includes only the bundled files.

The examples linked below load the needed MathJax components my hand, using the source files in MathJax's components directories (the files used to create the bundled components found in the bundle directory). The examples use the path @mathjax/src/components/js to access the component definitions, as MathJax's :file:package.json file is set up to map this to the components/mjs directory when used in an import command, and to components/cjs when used in a require() command, so the same address will give you the proper ES or CommonJS module for the mechanism you are using to load it.

All the examples begin with the following lines:

.. code-block:: javascript

import {MathJax} from '@mathjax/src/js/components/global.js'; import {insert} from '@mathjax/src/js/util/Options.js'; import '@mathjax/src/js/components/startup.js'; import '@mathjax/src/components/js/core/core.js'; import '@mathjax/src/components/js/adaptors/liteDOM/liteDOM.js';

(or the equivalent using require()). The first line sets up the global :js:data:MathJax variable, handling any existing :js:data:MathJax value as a MathJax configuration (in case the examples below are included in a larger application that sets up its own configuration). The second line obtains a utility for inserting values into the MathJax configuration, overriding existing values, if any. The third line loads the :ref:startup-component component, which will be called later to instantiate the needed MathJax objects and create the various typeset and conversion functions. The fourth line loads the core component, and the fifth loads the :ref:liteDOM-component component, which implements a limited DOM for use in node. (You would not load this component if you were using this technique to make a browser-based application, and there are other alternative adaptors that could be used if you need a more robust DOM implementation.)

Next we load the TeX components that we plan to use:

.. code-block:: javascript

import '@mathjax/src/components/js/input/tex-base/tex-base.js'; import '@mathjax/src/components/js/input/tex/extensions/ams/ams.js'; import '@mathjax/src/components/js/input/tex/extensions/newcommand/newcommand.js'; import '@mathjax/src/components/js/input/tex/extensions/color/color.js';

In this case, we use the tex-base component, which only includes the base configuration, whereas the :ref:tex-component component includes the :ref:require <tex-require> and the :ref:autoload <tex-autoload> components, which we can't support synchronously.

We also load the :ref:ams <tex-ams>, :ref:newcommand <tex-newcommand>, and :ref:color <tex-color> components. These are just for illustration; you can include whatever components you need for the expressions you will be processing.

Next, we load the CommonHTML output jax

.. code-block:: javascript

import '@mathjax/src/components/js/output/chtml/chtml.js';

though you could use the SVG output jax if you prefer.

Now that everything is loaded (though some of the examples load additional items), we configure the TeX input jax to use the pre-loaded extensions:

.. code-block:: javascript

insert(MathJax.config, { tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} } }, false);

This uses the :meth:insert() function that we loaded earlier.

Then we start up MathJax:

.. code-block:: javascript

MathJax.config.startup.ready();

and finally process some math and print the results:

.. code-block:: javascript

const math = process.argv[2] || ''; const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

Here, we take the math from the command line arguments, but you will likely obtain the math to be processed from elsewhere in your code. You may want to provide a :meth:typeset() function that encapsulates the code to do the typesetting.

This is the outline that is illustrated in the examples below. They include variations on this theme that show how to handle fonts synchronously in several different ways. There is also an example that handles speech generation, though that requires one asynchronous step, and only creates speech for the top-level element of the resulting expression.

.. _preload-import-tex:

Using the MathJax-TeX font

This example uses the mathjax-tex font, which is the original font-set used by MathJax v2 and v3. Because this font has limited character coverage it is not broken into multiple pieces, so you don't have to worry about dynamically loaded font data, so preloading the TeX extensions is all you have to worry about in order to be able to process math synchronously.

The lines that are required for this that differ from the outline given above are highlighted below.

Note that you will need to use npm or pnpm to install the @mathjax/mathjax-tex-font package in order to use the mathjax-tex font.

.. code-block:: javascript :linenos: :emphasize-lines: 20-23, 32-34

// // Load the TeX components that we want to use // import '@mathjax/src/components/js/input/tex-base/tex-base.js'; import '@mathjax/src/components/js/input/tex/extensions/ams/ams.js'; import '@mathjax/src/components/js/input/tex/extensions/newcommand/newcommand.js'; import '@mathjax/src/components/js/input/tex/extensions/color/color.js';

// // Load the output jax // import '@mathjax/src/components/js/output/chtml/chtml.js';

// // Load the mathjax-tex font // import {MathJaxTexFont} from '@mathjax/mathjax-tex-font/js/chtml.js';

// // Add the pre-loaded TeX extensions here, and specify the font // insert(MathJax.config, { tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} }, chtml: { fontData: MathJaxTexFont } }, false);

// // Start up MathJax // MathJax.config.startup.ready();

// // Convert some math synchronously // const math = process.argv[2] || ''; const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

.. _preload-import-newcm:

Using the MathJax-NewCM font

This example uses the default font for MathJax v4, the mathjax-newcm font, which is based on the New Computer Modern font. Because mathjax-newcm has extensive character coverage, it is broken into a number of separate files that are loaded dynamically when needed. That means producing output that uses mathjax-newcm can be asynchronous, as some character data may need to be loaded from additional files.

To use this font synchronously, you need to pre-load the font data files for the characters that you expect to need. The example below loads the calligraphic characters, but you could include additional import commands to load other ranges of characters. These files can be found in the node_modules/@mathjax/mathjax-tex-font/mjs/chtml/dynamic directory.

The mathjax-tex-font package should be installed automatically when you install the @mathjax/src npm package, so you shouldn't need to install it by hand, as you did for the mathjax-tex font in the previous example.

The lines that are required for this that differ from the outline given above are highlighted below.

.. code-block:: javascript :linenos: :emphasize-lines: 20-28, 37-39, 47-52

// // Load the output jax // import '@mathjax/src/components/js/output/chtml/chtml.js';

// // Load the font to use, and any dynamic font files // import {MathJaxNewcmFont} from '@mathjax/mathjax-newcm-font/js/chtml.js'; import '@mathjax/mathjax-newcm-font/js/chtml/dynamic/calligraphic.js'; // // ... load any additional ones here, and add them to the array below. // const fontPreloads = ['calligraphic'];

// // Add the pre-loaded TeX extensions here // insert(MathJax.config, { tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} }, chtml: { fontData: MathJaxNewcmFont } }, false);

// // Start up MathJax // MathJax.config.startup.ready();

// // Activate the dynamic font files // const font = MathJax.startup.document.outputJax.font; const dynamic = MathJaxNewcmFont.dynamicFiles; fontPreloads.forEach(name => dynamic[name].setup(font));

// // Convert some math synchronously // const math = process.argv[2] || ''; const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

This approach could also be used to handle any of the MathJax fonts available for v4 by first installing the needed font, and changing lines 23 to 28, line 38, and line 51 to refer to the correct font.

Technically, lines 37 to 39 are not needed, since the mathjax-newcm font is the default for MathJax v4, but these lines show how to configure MathJax for any font.

.. _preload-require-newcm:

A CommonJS Example

This example illustrates using require() rather than import in a CommonJS module. Because require() is synchronous, this makes it possible to load the dynamic font files in a loop rather than having to list them individually as we do above. MathJax provides a :js:meth:loadDynamicFilesSync() method for doing so, but it requires that you specify a mechanism for loading the files. This is usually an asynchronous method, but since we are using require(), we indicate that it is actually synchronous.

The changes needed for this are highlighted below. Of course, all the import commands have been changed to equivalent require() commands throughout.

.. code-block:: javascript :linenos: :emphasize-lines: 7-11, 30-34, 45-50

const {MathJax, combineDefaults} = require('@mathjax/src/js/components/global.js'); const {insert} = require('@mathjax/src/js/util/Options.js'); require('@mathjax/src/js/components/startup.js'); require('@mathjax/src/components/js/core/core.js'); require('@mathjax/src/components/js/adaptors/liteDOM/liteDOM.js');

// // Needed for asyncLoad below // const {mathjax} = require('@mathjax/src/js/mathjax.js'); const {Package} = require('@mathjax/src/js/components/package.js');

// // Load the TeX components that we plan to use // require('@mathjax/src/components/js/input/tex-base/tex-base.js'); require('@mathjax/src/components/js/input/tex/extensions/ams/ams.js'); require('@mathjax/src/components/js/input/tex/extensions/newcommand/newcommand.js'); require('@mathjax/src/components/js/input/tex/extensions/color/color.js');

// // Load the output jax // require('@mathjax/src/components/js/output/chtml/chtml.js');

// // Set the font path and add the pre-loaded TeX extensions here // insert(MathJax.config, { loader: { paths: { 'mathjax-newcm': '@mathjax/mathjax-newcm-font/js' } }, tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} } }, false);

// // Start up MathJax // MathJax.config.startup.ready();

// // Load the font dynamic files // mathjax.asyncLoad = (file) => require(Package.resolvePath(file)); mathjax.asyncIsSynchronous = true; MathJax.startup.document.outputJax.font.loadDynamicFilesSync();

// // Convert some math synchronously // const math = process.argv[2] || '' const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

This example loads all the dynamic font files, so you don't have to know which ones you will need. Note, however, that that can be a large number of files, with a large amount of data, much of which likely will never be used. This can increase the startup time for your application, so you may want to use the technique of individually loading only the files you actually need.

In an ES module, one could use

.. code-block:: javascript

mathjax.asyncLoad = (file) => import(Package.resolvePath(file)); await MathJax.startup.document.outputJax.font.loadDynamicFiles();

to load all the font files, but that is asynchronous, so you need to use await to wait for the command to complete. Be aware that that means other parts of your code could run before that is completed, so you will need to be careful not to call MathJax commands until after the loading is complete.

.. _preload-import-cjs:

Loading All Font Data Synchronously

In the previous example, we took advantage of require() to make the :js:meth:loadDynamicFilesSync() method available to load all the font data before processing any math. Although ES modules (using import and export) don't have a require() command, it is possible to define one that can be used to load CommonJS modules. MathJax provides a file that does that for you, so you don't need to know the details of how that works. This is done in line 12 below, which is the only new line added to the CommonJS example above.

In order for this to work, you need to use the CommonJS versions of all the MathJax modules. That is done by changing the js directory name to cjs everywhere it occurs in the import commands and the loader path definition.

.. code-block:: javascript :linenos: :emphasize-lines: 12

import {MathJax} from '@mathjax/src/cjs/components/global.js'; import {insert} from '@mathjax/src/cjs/util/Options.js'; import '@mathjax/src/cjs/components/startup.js'; import '@mathjax/src/components/cjs/core/core.js'; import '@mathjax/src/components/cjs/adaptors/liteDOM/liteDOM.js';

// // Needed for asyncLoad below // import {mathjax} from '@mathjax/src/cjs/mathjax.js'; import {Package} from '@mathjax/src/cjs/components/package.js'; import '@mathjax/src/components/require.mjs';

// // Load the TeX components that we want to use // import '@mathjax/src/components/cjs/input/tex-base/tex-base.js'; import '@mathjax/src/components/cjs/input/tex/extensions/ams/ams.js'; import '@mathjax/src/components/cjs/input/tex/extensions/newcommand/newcommand.js'; import '@mathjax/src/components/cjs/input/tex/extensions/color/color.js';

// // Load the output jax // import '@mathjax/src/components/cjs/output/chtml/chtml.js';

// // Set the font path and add the pre-loaded TeX extensions here // insert(MathJax.config, { loader: { paths: { 'mathjax-newcm': '@mathjax/mathjax-newcm-font/cjs' } }, tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} } }, false);

// // Start up MathJax // MathJax.config.startup.ready();

// // Convert some math synchronously // const math = process.argv[2] || ''; const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

If you don't use the cjs paths explicitly, the import commands will load the ES Modules, while the asyncLoad command, using require(), will load the CommonJS modules. That will cause all of MathJax to be loaded again from the cjs directories, and you will have two copies of everything. Then :js:meth:loadDynamicFilesSync() will load the dynamic files into the cjs copies, while your typesetting will be performed by the mjs versions, which don't have the dynamic files loaded, and that will lead to a MathJax retry error when any dynamic file is needed. That is, your loading of the dynamic files will have no effect, because they went into the wrong copy of MathJax.

.. _preload-import-speech:

Synchronous Typesetting with Speech

This example builds on the :ref:preload-import-newcm example by adding the needed code for generating speech output for the resulting expressions. This is accomplished by include the speech-rule-engine (SRE) code. Unfortunately, the startup code for SRE is inherently asynchronous, so you do need to handle one promise during initialization and wait for that before performing any typesetting operations, but once that one promise is resolved, you can work synchronously from there.

Since SRE uses require() to load its dependencies when it is used in node, we include the :file:components/require.mjs file to make that available from our ES module.

Lines 7 through 13 are the import commands needed to load SRE and other needed modules.

Lines 47 through 68 define a function that adds a speech string to the root node of the internal MathML tree, and then adds a renderAction to the document options that performs the :meth:addSpeech() action. The aria-label attribute will be included in the DOM elements generated by MathJax later in the conversion step.

Lines 70 through 75 give the asynchronous code that must be used to get SRE up and running before typesetting can be done synchronously. This waits for SRE to set itself up, passing it the locale and modality needed for the language specified as the second command-line argument to this script, then waits for SRE to be ready before startup up MathJax.

You may need to use npm or pnpm to install the speech-rule-engine npm module, if it isn't already installed.

.. code-block:: javascript :linenos: :emphasize-lines: 7-13, 47-68, 70-75

// // Load code for SRE // import '@mathjax/src/components/require.mjs'; import '@mathjax/src/components/js/a11y/semantic-enrich/semantic-enrich.js'; import {setupEngine, engineReady, toSpeech} from 'speech-rule-engine/js/common/system.js'; import {STATE} from '@mathjax/src/js/core/MathItem.js';

// // Load the output jax // import '@mathjax/src/components/js/output/chtml/chtml.js';

// // Add the pre-loaded TeX extensions here // insert(MathJax.config, { tex: { packages: {'[+]': ['ams', 'newcommand', 'color']} } }, false);

// // Add a speech string to the root math element // function addSpeech(item) { const speech = toSpeech(MathJax.startup.toMML(item.root)); item.root.attributes.set('aria-label', speech); }

// // Add a render action that computes the speech // insert(MathJax.config, { options: { renderActions: { addSpeech: [ STATE.COMPILED + 10, (doc) => {for (const item of doc.math) addSpeech(item)}, (item, doc) => addSpeech(item) ] } } }, false);

// // Start up SRE // const locale = process.argv[3] || 'en'; const modality = locale === 'nemeth' || locale === 'euro' ? 'braille' : 'speech'; await setupEngine({modality, locale}).then(() => engineReady());

// // Start up MathJax // MathJax.config.startup.ready();

// // Activate the dynamic font files // const font = MathJax.startup.document.outputJax.font; const dynamic = MathJaxNewcmFont.dynamicFiles; fontPreloads.forEach(name => dynamic[name].setup(font));

// // Convert some math synchronously // const math = process.argv[2] || ''; const adaptor = MathJax.startup.adaptor; console.log(adaptor.outerHTML(MathJax.tex2chtml(math)));

If you don't want to, or can't, use await, you can add one more then() clause whose function starts up the main code for your application instead.

More examples are available in the MathJax node demos <https://github.com/mathjax/MathJax-demos-node#MathJax-demos-node>__ for using MathJax from a node application. In particular, see the preloading examples <https://github.com/mathjax/MathJax-demos-node/tree/master/preload#preloaded-component-examples>__ for illustrations of how to load MathJax components by hand in a node application.

|-----|