gl-matrix: the README tells you to turn off the library's own default
Javascript Matrix and Vector library for High Performance WebGL apps
At a glance
- What is it?
- A matrix and vector library for WebGL whose project page advises swapping its hand-tuned typed arrays for plain JavaScript arrays in modern browsers, whose package is marked private while published to a public registry, and whose build runs a license-version update script on every run.
- Who is it for?
- gl-matrix is a reasonable choice if you are doing per-frame vector math in a browser and want typed arrays, per-type import paths and hand-tuned functions. It is a poor fit if you want a CommonJS drop-in, because the package's entry points are all ES modules, or if you want a release cadence you can plan around.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 125 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- toji/gl-matrix5,706 ★ · +10
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| toji/gl-matrix | 5.7k | 5.7k |
10 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The project page advises abandoning its own default
The pitch is speed. The page says the library is designed to perform vector and matrix operations stupidly fast, by hand-tuning each function and encouraging efficient usage patterns through the API conventions.
Then, a few lines later, this:
Regarding the current performance in modern web browsers, calling `glMatrix.setMatrixArrayType(Array)` to use normal arrays instead of Float32Arrays can greatly increase the performance.So the mechanism the library is built around, storing numbers in typed arrays, is the thing the page advises switching off if you want the best results on a current engine. The change is one call and it is global to the library rather than per object.
There is an honest tension here rather than a contradiction. The typed-array layout was the right trade-off when JavaScript engines were slower, and a library that stores a matrix in a fixed-width buffer has real advantages for upload to the graphics card. But the page is telling you that the engine's own optimisations now favour plain arrays, which means the library's central design decision is a historical one. Nothing on the page says when that stopped being true or which engine versions are meant.
Eleven entry points, and the built output is in version control
The package exposes a subpath for every type it implements, plus an aggregate entry and a shared helper module:
"./mat4": "./dist/esm/mat4.js",
"./quat": "./dist/esm/quat.js",
"./vec3": "./dist/esm/vec3.js"Eleven in total. The practical effect is that an application can import one matrix type instead of the whole library, which matters for a library that is otherwise pure arithmetic with no side effects, and the package declares that side effect free so a bundler can drop what is unused.
The layout is entirely ES modules. The type field marks the package as a module, and both the main field and the module field point at the same aggregate file:
"main": "./dist/esm/index.js",
"module": "./dist/esm/index.js",There is a UMD build produced as well, but it is not what either of those fields resolves to. A CommonJS consumer therefore gets the ES module file.
And the whole `dist` directory is checked into the repository, even though the build script begins by deleting it. The committed build is what a browser loading the library from a file sees.
The build script rewrites your source files as its second step
The full build is one chain, and the order matters:
"build": "del dist && npm run update-license-version && npm run build-umd && npm run build-esm && npm run build-dts && node ./utils/build.js"The second step is not compilation. It runs a script in the utilities directory whose name says exactly what it does: it updates the license version.
Two other scripts finish the chain, one after the declaration build and one at the end, both custom and both living in the same utilities directory.
TypeScript declarations are emitted as AMD modules, then bundled by hand
Generating the type declarations is the most unusual line in the build. It runs the TypeScript compiler over JavaScript sources with declaration output enabled, and asks for AMD modules with Node resolution, funnelled into a single output file:
"build-dts": "tsc --allowJs --declaration --emitDeclarationOnly --module amd --moduleResolution node --outFile ./dist/index.d.ts ./src/index.js ./src/types.d.ts && node ./utils/bundle-dts.js && tsc --noEmit ./dist/index.d.ts"Three steps. Emit declarations as AMD into one file, run a custom script to bundle them, then type-check the result.
The choice of AMD as the intermediate module format is what makes the bundling step necessary: the compiler will not combine several declaration files into one ES module declaration on its own, so the project wrote a script to do it. The final type check is the part worth keeping, because a hand-written bundler can produce a file that parses but does not resolve, and the check runs against the emitted file rather than the sources.
The types field points at that single bundled file, so consumers see one declaration file for the whole library.
The package is marked private and published anyway
One field in the package metadata is worth stopping on:
"private": true,That field tells the package manager not to publish. It is set in a package whose own project page carries a badge linking its page on the public registry, and which is installed by name in the instructions elsewhere in the ecosystem.
Both things are true at once, because the field only prevents a publish from happening; it does not unpublish anything. So this is a guard against an accidental release rather than a statement about distribution, and somebody put it there on purpose.
The likely reason is the version handling. The metadata carries its own version string, and so does the project:
"version": "3.4.4",There is a separate file at the root holding a version too, so the value exists in at least two places. Any of those can drift from the published artifact.
Releases roughly four years apart, and a tree ahead of all of them
The tag history explains the guard above.
A 3.3.0 in April 2020. A 3.4.1 in October 2021, eighteen months later. A 3.4.4 in August 2025, close to four years after that. Three tags across six years, two of them patch releases on a minor version line that never moved past 3.4.
The repository is not archived, and the default branch was pushed to on 2026-07-13, about eleven months after the newest tag. So the code anyone clones from the default branch is a year newer than anything they can install from a tag.
For a library whose whole argument is that it is hand-tuned for speed, that cadence is the main risk. The optimisation work that justifies the design is exactly the kind of change that needs engine-specific attention, and there is no release cadence to receive it in.
A CI badge for a discontinued service, and documentation over plain http
The badge row at the top of the page links a build status on a CI service that has been retired under its original domain, and the repository carries a configuration file for that same service alongside a directory for the current one.
The links out of the project page have the same dated quality. The homepage is plain http, and so is the homepage field in the package metadata. The recommended tutorial is a section of a computer graphics textbook hosted on a university mathematics server, over plain http, and it predates the current version by a long way.
Then there is the odd one: the page recommends a Babel plugin written by somebody outside the project, whose purpose is to make writing the API nicer. A package that now ships native ES modules with a subpath export per type does not need a transform to make its syntax nicer, which suggests that recommendation was written for the previous major version and never revisited.
Two contributors are named in the metadata, and the licence file at the root carries a markdown extension rather than the bare name.
Editorial conclusion
gl-matrix is a reasonable choice if you are doing per-frame vector math in a browser and want typed arrays, per-type import paths and hand-tuned functions. It is a poor fit if you want a CommonJS drop-in, because the package's entry points are all ES modules, or if you want a release cadence you can plan around. Three things to check. Read the array type note on the project page before optimising anything, because it says the default is not the fastest option on current engines. Check which distribution you actually import, since the package exposes eleven subpaths and the default export is the only aggregate one. And if you vendor the library, remember the built output is committed and the build script runs a license-version update as its second step.
Frequently asked questions
how to use gl matrix
Import the package, or one of its eleven subpath entries for a single matrix or vector type. All entry points are ES modules, and the types field points at a single bundled declaration file. The page also notes that switching the array type to plain arrays can greatly increase performance in current browsers.
what is gl matrix
It is a matrix and vector math library for realtime 3D graphics and physics simulations in the browser, written in JavaScript for WebGL applications. The project describes it as hand-tuning each function for speed and using API conventions to encourage efficient usage.
What are the 7 types of matrix?
That question is about mathematics rather than this library. What gl-matrix implements, by its own export map, is mat2, mat2d, mat3 and mat4 matrices, quat and quat2 quaternions, and vec2, vec3 and vec4 vectors, plus a shared common entry.
Is gl-matrix still being worked on?
The repository is not archived and the default branch was pushed to on 2026-07-13. The newest tag is 3.4.4 from 2025-08-08, and the two before it are 3.4.1 from 2021 and 3.3.0 from 2020, so the default branch is about eleven months ahead of the newest release.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/toji-gl-matrix)Star history chart for your README
[](https://hysenlabs.com/projects/toji-gl-matrix)Was this useful?