# MathJax-src: the TypeScript source behind MathJax 4.x

> MathJax-src is the TypeScript repository that compiles into the MathJax components served from CDNs and published to npm. It is for people who need to build MathJax themselves, not for page authors who can load a script tag.

**mathjax/MathJax-src** — MathJax source code for version 3 and beyond

- Repository: https://github.com/mathjax/MathJax-src
- Website: https://www.mathjax.org/
- Stars: 2,401 · Forks: 245
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/mathjax-mathjax-src

## What MathJax-src actually is, and who should clone it

The README is explicit that this repository holds source files written in TypeScript, which are compiled into JavaScript and then combined into component files for use on the web. Those component files are what most people mean by "MathJax": they are hosted on CDN services and also published to the MathJax Component Repository. So the audience for MathJax-src is narrow. It is developers who need to change the engine, add an input or output format, build a trimmed component, or run typesetting in a Node process. It is not the entry point for someone who wants equations on a blog post. That person should load the component script from a CDN and never touch this repository. The distinction matters because the two paths have completely different failure modes: a CDN user can break their page with a bad config, while a source user can break their build with a bad toolchain.

## How the TypeScript source becomes a browser component

The pipeline is visible in the repository layout. The ts/ directory holds the TypeScript sources; the build compiles those to JavaScript, and a separate step in components/ assembles the compiled files into the bundled component files. The package.json describes the published artifact as including both: the description says the package "includes the source code as well as the packaged components", and the exports map exposes several entry points. The root export resolves to bundle/node-main.mjs for import and bundle/node-main.cjs for require, while ./source resolves to components/mjs/node-main/node-main.mjs and components/cjs/node-main/node-main.cjs. There is also a ./js/* export that maps to ./mjs/* and ./cjs/*. That split is the whole architecture in miniature: one path gives you the prebuilt Node bundle, the other gives you the component layer that the bundle is built from. If you are debugging why a configuration key has no effect, you want the component path. If you just want to typeset a string in a script, the bundle path is shorter.

## Installing MathJax from npm and typesetting your first formula

For a Node application the README gives two packages with different weight. The mathjax package is the component-based route, and the README installs it with a version tag:

```bash
npm install mathjax@4
```

After that you import the package, call init with a configuration object, and then call a conversion method. The README's own example loads the TeX input and SVG output and converts a fraction:

```js
import MathJax from 'mathjax';
await MathJax.init({
  loader: {load: ['input/tex', 'output/svg']}
});
const svg = await MathJax.tex2svgPromise('\\frac{1}{x^2-1}', {display: true});
console.log(MathJax.startup.adaptor.serializeXML(svg));
```

The loader key is what pulls in the input and output modules; without it, tex2svgPromise has nothing to convert with. The README also shows an ES5 variant using require and MathJax.tex2svg rather than the promise form, and it carries a warning worth repeating: this technique is for node-based applications only, not for browsers, because it sets up an alternative DOM implementation. The README states plainly that this setup "will not work properly in the browser, even if you webpack it or use some other bundler".

If you want the JavaScript modules directly rather than the components, the README points at a second package:

```bash
npm install @mathjax/src
```

That installs ts/ (the TypeScript sources), js/ (compiled JavaScript), components/ (build tools and control files) and bundle/ (the packaged component files) under node_modules/@mathjax/src/. The README describes this as the greatest flexibility with more coding required. Building the repository itself is a three-command sequence:

```bash
git clone https://github.com/mathjax/MathJax-src.git mathjax-src
cd mathjax-src
npm run --silent build-all
```

The README adds a Windows-specific step, setting the npm script shell to Git Bash, because the build scripts that MathJax defines in package.json require bash. On Windows, run that configuration command before build-all, or the scripts will not execute as written.

## The Node-only DOM shim is the trap most integrators hit

The clearest limitation is documented by the project itself, which is unusual and useful. The Node examples work because MathJax substitutes an alternative DOM implementation, and the README warns that this depends on node and the local file system in other ways. Bundling that code for the browser produces something that loads and then misbehaves, and the README says so explicitly rather than leaving it to bug reports. The practical consequence: if your architecture is a single JavaScript bundle that runs in both Node and the browser, you cannot share one MathJax initialization path. You need the component script in the browser and the Node package on the server. That is a real design constraint, not a footnote, and it is the most common way a first integration goes wrong. The second constraint is the build toolchain. The repository ships pnpm-lock.yaml and pnpm-workspace.yaml, and the README's Windows note names pnpm when explaining the bash requirement, so the build assumes that package manager rather than npm or yarn. Working from the GitHub repository directly means accepting that toolchain.

## When a script tag beats the source repository

The alternative to MathJax-src is MathJax itself, the component files that the source compiles into. The README's browser example is a single tag:

```html
<script src="https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js" defer></script>
```

That file bundles TeX and MathML input with CommonHTML output. The difference in approach is not cosmetic. With the CDN component you get a fixed combination of input and output modules chosen by whoever built that component, configured through an inline MathJax object on the page. With the source repository you choose the modules yourself, at the cost of running the build. For a documentation site, a CMS, or a course page, the CDN route is the correct one and the source route is wasted effort. The source route earns its keep when no published component matches your needs, for example when you want a specific input/output pairing that the standard components do not offer, or when you need to patch engine behaviour. A related but different case is server-side rendering in another language: the README lists no Python package here, so a Python pipeline has to call out to Node or use a separate binding rather than this repository.

## Maintenance cadence, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-25, three days before this writing, so the project is being worked on now. Releases are frequent: 4.1.1 on 2026-02-19, 4.1.2 on 2026-05-03, and 4.1.3 on 2026-07-03. The pattern suggests patch releases roughly every two to three months, which is a manageable upgrade rhythm for a dependency you build against. The cost of upgrading is not the version bump itself but the rebuild: if you consume @mathjax/src and compile your own component, every MathJax release means re-running build-all and re-testing your component, because the compiled output changes underneath you. If you consume the CDN component, an upgrade is a URL change and a page reload. That asymmetry should inform which path you pick. On licensing, package.json declares Apache-2.0 and the repository carries a LICENSE file at the top level. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, with the usual obligations around retaining notices and stating changes; the README and package.json do not discuss trademark use of the MathJax name, so if you redistribute a modified engine under a similar name, that is a question for your own counsel rather than something this repository answers.

## Conclusion

Adopt MathJax-src if you need to modify MathJax itself, build custom components, or run typesetting server-side through the mathjax or @mathjax/src packages. Do not adopt it if a script tag pointing at the jsDelivr component file already covers your page; the source repository adds a pnpm workspace, a TypeScript build and a Node DOM shim you do not need in a browser. Before committing, verify that the component you intend to ship exists in the build output, that your Node version satisfies package.json, and that the Apache-2.0 licence terms fit how you redistribute the compiled bundle.

## FAQ

### What is MathJax used for?

MathJax is an open-source JavaScript display engine for LaTeX, MathML, and AsciiMath notation, and the README says it works in all modern browsers with built-in support for assistive technology such as screen readers. Page authors include MathJax and some mathematics in a web page, and MathJax does the rest.

### Is MathJax safe?

The repository does not make a security claim. What the material does show is that package.json declares the Apache-2.0 licence, which permits commercial use and modification and includes an explicit patent grant.

### Is MathJax similar to LaTeX?

MathJax is not a LaTeX distribution. It is a display engine that accepts LaTeX notation as one of three input formats, alongside MathML and AsciiMath, and renders it in the browser or in a Node application.

### Is MathML still used?

MathJax treats MathML as a first-class input format: the browser component named in the README, tex-mml-chtml.js, bundles both TeX and MathML input, and the package keywords list MathML alongside TeX and AsciiMath.

## Sources

- [License: Apache-2.0](https://github.com/mathjax/MathJax-src/blob/master/LICENSE)
- [mathjax/MathJax-src on GitHub](https://github.com/mathjax/MathJax-src)
- [Project website](https://www.mathjax.org/)
- [README](https://github.com/mathjax/MathJax-src/blob/master/README.md)
- [Releases](https://github.com/mathjax/MathJax-src/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mathjax-mathjax-src