.. _node-components:

################################ Using MathJax Components in Node ################################

It is possible to use MathJax in a node application in essentially the same way that it is used in a browser. In particular, you can load MathJax components and configure MathJax using a global :js:data:MathJax object and load a :ref:combined component <combined-components> file or the :ref:startup-component component via node's import or require() commands.

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 change the require() or import statements accordingly in the examples below if you have loaded mathjax@4 or obtained MathJax from the MathJax-src GitHub repository.

In MathJax, the loading of components is asynchronous, and so you may need to use promises or the await command to mediate the flow of your program, particularly program startup. Once MathJax's components are loaded, however, you can call the non-promise-based functions, but should use the promise-based ones if you want to support autoloading of extensions, the \require macro in TeX input, or the v4 fonts with larger character coverage.

.. 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.

The :ref:synchronous examples <node-preload> show how to operate synchronously from the outset, if that is required.

Configuring and Loading Components in Node

As with MathJax in a browser, using MathJax components in a node application consists of two steps: configuring MathJax, and Loading a MathJax combined component to process the configuration. Just as in a browser, the configuration is specified in the global :js:data:MathJax variable.

.. _web-vs-node:

Configuration for Node vs. the Web

If you are using MathJax components as part of a larger application that will be bundled for use in a web browser, then your MathJax configuration should be the same as the configuration you would use if you were loading MathJax into the web page directly, with one exception: you may need to provide the URL where MathJax should load any extensions that are needed once MathJax is running. Normally, MathJax determines that URL based on the src attribute of the script tag that loaded it, but since MathJax is part of your larger application, that URL is probably not appropriate, so you will need to specify the correct one yourself.

This is done using the :js:data:mathjax property of the :js:data:paths section in the :js:data:loader block of your MathJax configuration. For example,

.. code-block:: javascript

global.MathJax = { loader: { paths: { mathjax: 'https://cdn.jsdelivr.net/npm/mathjax@4' } } }

would set things up so that extensions would be loaded from the jsDelivr CDN. You could, of course, make the extensions available on your own server and set the URL to point to that.

If you are using MathJax components as part of a server-side or command-line application, you should set the :js:data:mathjax path to @mathjax/src/bundle instead:

.. code-block:: javascript

global.MathJax = { loader: { paths: { mathjax: '@mathjax/src/bundle' } } }

so that MathJax will take additional components from the bundle directory.

.. note::

In version 4, the bundle directory replaces the es5 directory from version 3.

For non-browser applications, there are two additional steps you need to take. First, you must tell MathJax to use import() or require() as the mechanism for loading external files, and second, you need to load a non-browser :ref:DOM adaptor <node-DOM-adaptor>. MathJax provides a light-weight DOM implementation (called liteDOM) that is sufficient for MathJax's needs without unnecessary overhead, so you probably want to use that. If you need a more full-featured DOM implementation, you can use another one, such as jsdom or linkedom (MathJax does provide adaptors for these). It is even possible to use puppeteer with headless Chrome in order to be able to access a full DOM implementation from node.

Both of these features are set in the :js:data:loader block of your MathJax configuration object, as illustrated in the sections below.

.. _node-import-configuration:

Configuring MathJax for Use with import

Because the configuration must be in place before the MathJax component is loaded, if you are using import commands rather than require(), that means you either need to put the MathJax configuration into a separate file to be imported before MathJax itself, or you need to use the promise-based import() function to load MathJax.

So you could create a file called mathjax-config.mjs containing

.. code-block:: javascript

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: (file => import(file)) }, // additional configuration here };

and then use

.. code-block:: javascript

import './mathjax-config.js'; import '@mathjax/src/bundle/tex-chtml.js'; await MathJax.startup.promise;

// your code that uses MathJax here

MathJax.done();

to load the tex-chtml combined component with that configuration, and wait for MathJax to set itself up.

.. note::

In MathJax v4, the speech generation is performed in web-workers (in the browser) or worker-threads (in node applications), and once these are started, they will prevent the node application from ending if they are not shut down. So v4 includes the :js:meth:MathJax.done() function that terminates the workers, thus allowing the node program to end. You should call this when your program is ready to end so that it can shut down properly.

Alternatively, you could do

.. code-block:: javascript

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: (file => import(file)) }, // additional configuration here }; await import('@mathjax/src/bundle/tex-chtml.js'); await MathJax.startup.promise;

// your code that uses MathJax here

MathJax.done();

to include the configuration in-line before loading the tex-chtml component.

.. note::

ES6 modules usually use import, and require() is not available, but it is possible to define require() if you are making a command-line or server-side application. MathJax provides a file that does that for you, so if you add

.. code-block:: javascript

  import '@mathjax/src/bundle/require.mjs';

to your code, you can then use require() as described in the following section.

.. _node-locale-configuration:

Configuring the Speech Locale

The default speech language is English, and the default Braille code is Nemeth. You can use the :js:data:sre block of the :js:data:options section of your MathJax configuration to specify a different locale or Braille version, as illustrated below.

.. code-block:: javascript

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: (file) => import(file) }, options: { sre: { locale: 'de' } } // additional configuration here };

await import('@mathjax/src/bundle/tex-chtml.js'); await MathJax.startup.promise;

// your code that uses MathJax here

MathJax.done();

which configures MathJax to produce speech strings in German rather than English.

.. _node-cjs-configuration:

Configuring MathJax for Use with require()

To use MathJax components in a CommonJS module, first set up the MathJax configuration, and then require() the combined component you want to load. So you can do

.. code-block:: javascript

MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: require }, // additional configuration here }; require('@mathjax/src/bundle/tex-chtml.js'); MathJax.startup.promise .then(() => { //your MathJax code here }) .catch((err) => console.error(err.message)) .then(() => MathJax.done());

to configure MathJax for use with the tex-chtml combined component, and then wait for MathJax to start up, perform your commands (with error trapping), and then shut down MathJax.

.. _node-startup-component:

Loading Individual Components

If you are using MathJax components in a server-side or command-line application, the combined components that MathJax provides may include components that you don't need (such as the menu code and expression explorer). So you may want to configure MathJax explicitly to use only the components that you need. You do this by listing the needed components in the load array of the loader section of the MathJx configuration, and then load the startup.js module rather than a combined component.

For example,

.. code-block:: javascript

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['input/tex', 'output/svg', 'adaptors/liteDOM'], require: (file => import(file)), }, output: {font: 'mathjax-newcm'} } await import('@mathjax/src/bundle/startup.js'); await MathJax.startup.promise;

would load only the TeX input jax and the SVG output jax, along with the liteDOM adaptor, but without loading the menu code, the assistive tools, or any other components. Because the input/tex component includes the :ref:require <tex-require> and :ref:autoload <tex-autoload> extensions, the TeX that you process could still load TeX extensions that are needed.

Because the output/svg component does not include a font, you need to configure that separately in the :js:data:output section of the configuration, as shown.

.. _node-load-source:

Loading MathJax Components from Source

The examples above all load the webpacked versions of MathJax's components. It is possible to load the files from the source .js files in the mjs or cjs directories, which may be useful if you are modifying the MathJax source files and want to test your changes without having to repack all the components.

To do this, you should set the :js:data:source mapping in the :js:data:loader section of the MathJax configuration, and then load the combined component from its source file in the components directory rather than the bundle directory. The :file:source.js file in components/mjs or components/cjs directory contains the mapping of component names to their source definitions, and you can use that to set the :js:data:source field of your MathJax configuration.

You can obtain the :file:source.js file using :file:@mathjax/src/components/js/source.js, and it will select the mjs or cjs directory depending on whether you use import or require() to load it. So for use in ES6 modules, you can do

.. code-block:: javascript

import {source} from '@mathjax/src/components/js/source.js'; import '@mathjax/src/bundle/require.mjs'; // needed by speech-rule engine

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: (file => import(file)), source: source } // additional configuration here } await import(source['tex-chtml']); await MathJax.startup.promise;

// your code that uses MathJax here

MathJax.done();

while for CommonJS modules, you can do

.. code-block:: javascript

const {source} = require('@mathjax/src/components/js/source.js');

MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: require, source: source } // additional configuration here } require(source['tex-chtml']); MathJax.startup.promise .then(() => { //your MathJax code here }) .catch((err) => console.error(err.message)) .then(() => MathJax.done());

.. _node-load-component:

Calling MathJax from Components

Once you have loaded a combined component file (or the startup component), you can use the normal MathJax commands to typeset mathematics. For example, in a browser application, you can call :js:meth:MathJax.typesetPromise() to typeset the page.

For a command-line application, you could do

.. code-block:: javascript

const EM = 16; // size of an em in pixels const EX = 8; // size of an ex in pixels const WIDTH = 80 * EM; // width of container for linebreaking

function typeset(math, display = true) { return MathJax.tex2svgPromise(math, { display: display, em: EM, ex: EX, containerWidth: WIDTH }).then((node) => { const adaptor = MathJax.startup.adaptor; return(adaptor.serializeXML(adaptor.tags(node, 'svg')[0])); }).catch(err => console.error(err)); }

to define a :meth:typeset() command that takes a TeX string and an optional boolean that specifies whether the typesetting should be in display mode or in-line mode and returns a promise that is resolved when the typesetting is complete (while handling any waiting that had to be done to load extensions, fonts, etc.).

The :meth:typeset() promise returns the serialized SVG output, so that you could do

.. code-block:: javascript

const svg = await typeset('\sqrt{1+x^2}');

to get the SVG output. See the :ref:stand-alone-svg section for an example of generating SVG images that handles the CSS needed by some expressions in MathJax.

.. _node-component-example:

Examples of Components in Node

The following combines some of the ideas described above into a single, complete example of a command-line tool that takes three arguments: a TeX string to typeset, the language locale to use, and the Braille format to use. The last two are optional, and default to en and nemeth.

.. code-block:: javascript :linenos:

global.MathJax = { loader: { paths: {mathjax: '@mathjax/src/bundle'}, load: ['adaptors/liteDOM'], require: (file) => import(file) }, options: { sre: { locale: process.argv[3] || 'en', braille: process.argv[4] || 'nemeth' } }, output: { linebreaks: { inline: false, } }, // additional configuration here };

await import('@mathjax/src/bundle/tex-svg.js'); await MathJax.startup.promise;

const EM = 16; // size of an em in pixels const EX = 8; // size of an ex in pixels const WIDTH = 80 * EM; // width of container for linebreaking

function typeset(math, display = true) { return MathJax.tex2svgPromise(math, { display: display, em: EM, ex: EX, containerWidth: WIDTH }).then((node) => { const adaptor = MathJax.startup.adaptor; return(adaptor.serializeXML(adaptor.tags(node, 'svg')[0])); }).catch(err => console.error(err)); }

const math = process.argv[2] || ''; const svg = await typeset(math); console.log(svg);

MathJax.done();

See the :ref:stand-alone-svg section for an example of generating SVG images that handles the CSS needed by some expressions in MathJax.

See the MathJax node demos <https://github.com/mathjax/MathJax-demos-node#MathJax-demos-node>__ for more examples of how to use MathJax from a node application. In particular, see the component-based examples <https://github.com/mathjax/MathJax-demos-node/tree/master/component#component-based-examples>__ for illustrations of how to configure and load MathJax components.

|-----|