gl-matrix

library3.4.4jsnpmunverified

glMatrix is a high-performance JavaScript library for vector and matrix mathematics, specifically optimized for real-time 3D graphics applications like those built with WebGL. It leverages `Float32Array` by default for numerical operations, ensuring maximum performance by minimizing garbage collection and memory overhead. The current stable version is 3.4.4, with releases occurring periodically to address bug fixes, introduce performance improvements, and maintain compatibility with modern JavaScript and TypeScript environments. Key differentiators include its focus on raw speed, a comprehensive set of operations for `vec2`, `vec3`, `vec4`, `mat3`, `mat4`, and `quat` types, and its design to prevent global namespace pollution by using named imports or a single `glMatrix` global object. It also supports cherry-picking individual modules for better tree-shaking.

data http-networking web-framework serialization

npm install gl-matrix

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GL-MATRIX

gl-matrix

datajavascriptv3.4.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mat4

✓ import { mat4 } from 'gl-matrix';

✗ const mat4 = require('gl-matrix').mat4;

ESM is the primary export since v3.4.4. The CommonJS `require` pattern is no longer officially supported and will likely fail in modern environments.

vec2 (cherry-picked module)

✓ import * as vec2 from 'gl-matrix/vec2';

✗ import { create } from 'gl-matrix/vec2';

Introduced in v3.0.0 for better tree-shaking and modularity. Individual modules export a namespace, so use `import * as Name from 'module/path'`.

glMatrix (global object)

✓ <script src="path/to/dist/gl-matrix.js"></script> <script> const matrix = glMatrix.mat4.create(); </script>

✗ <script src="path/to/dist/gl-matrix.js"></script> <script> const matrix = mat4.create(); </script>

Since v3.0.0, when including `dist/gl-matrix.js` directly in a browser via a `<script>` tag, all functions are nested under the global `glMatrix` object to avoid polluting the global scope. Prior to v3.0.0, functions like `mat4.create()` were globally available.

Mat4 (TypeScript Type)

✓ import type { mat4 as Mat4Type } from 'gl-matrix';

TypeScript type definitions are included with the package since v3.2.0, with improved `readonly` types in v3.3.0. Use `import type` for type-only imports to avoid bundling issues.

Demonstrates basic setup of projection and view matrices for a 3D scene, along with common model matrix transformations like translation and rotation using `mat4` and `vec3`.

import { mat4, vec3 } from 'gl-matrix'; /** * Sets up a basic camera's projection and view matrices. * @param {mat4} projectionMatrix The matrix to store the projection results. * @param {mat4} viewMatrix The matrix to store the view results. * @param {number} aspectRatio The aspect ratio of the viewport (width / height). */ function setupCamera(projectionMatrix: mat4, viewMatrix: mat4, aspectRatio: number): void { // Create a perspective projection matrix (Field of View, Aspect, Near, Far) mat4.perspective(projectionMatrix, Math.PI / 4, aspectRatio, 0.1, 100.0); // Create a view matrix (camera position, target, up vector) const cameraPosition = vec3.fromValues(0, 0, 5); const target = vec3.fromValues(0, 0, 0); const up = vec3.fromValues(0, 1, 0); mat4.lookAt(viewMatrix, cameraPosition, target, up); console.log('Initialized Projection Matrix:', projectionMatrix); console.log('Initialized View Matrix:', viewMatrix); } const projection = mat4.create(); const view = mat4.create(); setupCamera(projection, view, window.innerWidth / window.innerHeight); // Example: Create a model matrix for an object and apply transformations const modelMatrix = mat4.create(); const translationVector = vec3.fromValues(1, 0.5, 0); mat4.translate(modelMatrix, modelMatrix, translationVector); // Translate by (1, 0.5, 0) const rotationAxis = vec3.fromValues(0, 1, 0); // Rotate around Y axis mat4.rotate(modelMatrix, modelMatrix, Math.PI / 4, rotationAxis); // Rotate 45 degrees console.log('Model Matrix (translated and rotated):', modelMatrix); // To reset the matrix to identity: mat4.identity(modelMatrix); console.log('Model Matrix (reset to identity):', modelMatrix);

Debug

Known issues

breakingStarting with `v3.4.4`, gl-matrix explicitly transitioned to being an ES Module (`"type": "module"` in `package.json`). This means that CommonJS `require()` statements will generally no longer work out-of-the-box and require explicit ESM support in your environment.

fix

Update your build setup or runtime environment to use ES Module imports (`import ... from 'gl-matrix'`). For Node.js, ensure your `package.json` also has `"type": "module"` or use `.mjs` extensions for files importing gl-matrix. If you must use CommonJS, consider transpiling your code or sticking to an older, non-ESM version, though this is not recommended for long-term maintenance.

affects: >=3.4.4

breakingIn `v3.0.0`, the global namespace handling for direct `<script>` includes changed. Instead of polluting the global scope with individual functions like `vec2`, `mat4`, etc., all functionality is now exposed under a single global `glMatrix` object (e.g., `glMatrix.mat4.create()`).

fix

Update existing browser scripts that rely on global access to prepend `glMatrix.` to all calls (e.g., `mat4.create()` becomes `glMatrix.mat4.create()`). Alternatively, for modern browser development, use ES Module imports with a bundler.

affects: >=3.0.0

gotchaVersion `3.4.0` was briefly published to npm with a breaking change related to Node.js module handling and then quickly deprecated in favor of `3.4.1` to avoid the breakage. Developers who accidentally installed `3.4.0` would have encountered issues.

fix

Ensure you are using `3.4.1` or newer if you intended to update gl-matrix around that time. Version `3.4.0` should be explicitly avoided.

affects: =3.4.0

gotchaWhile gl-matrix defaults to using `Float32Array` for performance, the library allows overriding this behavior with `glMatrix.setMatrixArrayType(Array)`. However, using standard JavaScript `Array`s can sometimes *decrease* performance in modern web browsers, contrary to older advice, due to `Float32Array` optimizations in VM engines.

fix

For most high-performance scenarios, stick with the default `Float32Array`. Only switch to `Array` after thorough profiling if a specific performance bottleneck is identified related to `Float32Array` usage in your target environment.

affects: >=3.0.0

gotchaPrior to `v3.2.0`, `gl-matrix` did not ship TypeScript type definitions (`.d.ts` files) directly with the package. This meant users had to rely on `@types/gl-matrix` from DefinitelyTyped, which might not always perfectly align with the library's version or latest features.

fix

For modern TypeScript projects, use `gl-matrix@^3.2.0` or newer to get official, integrated type support. If constrained to older versions, ensure `@types/gl-matrix` is installed and its version is compatible with your `gl-matrix` version.

affects: <3.2.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `gl-matrix` with CommonJS `require()` syntax or in a CommonJS module when the package is now ESM-only (since v3.4.4).

fix

Update your project to use ES Module `import` syntax (`import { mat4 } from 'gl-matrix';`) and ensure your Node.js environment or bundler correctly handles ESM. For Node.js, this often means adding `"type": "module"` to your `package.json` or using the `.mjs` file extension for the importing file.

Uncaught ReferenceError: mat4 is not defined

In a browser environment, `dist/gl-matrix.js` was included via a `<script>` tag, but functions were called directly (e.g., `mat4.create()`) without using the `glMatrix` global object wrapper (introduced in v3.0.0).

fix

Access functions via the `glMatrix` global object: `glMatrix.mat4.create()` instead of `mat4.create()`. Alternatively, use ES Module imports with a bundler for modern browser development.

Property 'create' does not exist on type 'typeof import("gl-matrix/dist/gl-matrix")' or 'Type 'Float32Array' is not assignable to type 'number[]''

TypeScript type mismatches when using older versions of `gl-matrix` without official types or with an outdated `@types/gl-matrix` package, or incorrect type assertions.

fix

Ensure `gl-matrix` is at least `v3.2.0` for integrated type definitions. If using older versions, verify that `@types/gl-matrix` is installed and compatible. When declaring array types, remember gl-matrix defaults to `Float32Array` (`import type { vec3 } from 'gl-matrix';` will correctly infer this).

Error: Cannot use 'import.meta' outside a module

This error occurs in Node.js when `gl-matrix` (an ESM module since v3.4.4) is imported into a file that Node.js interprets as CommonJS (e.g., a `.js` file without `"type": "module"` in `package.json`). `import.meta` is an ESM-specific feature used internally by gl-matrix.

fix

Ensure the file importing `gl-matrix` is also treated as an ES Module by Node.js. This typically means adding `"type": "module"` to your project's `package.json` or using the `.mjs` file extension for the importing file.

Upgrade

Version history

3.4.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/toji/gl-matrix ↗

packagehttps://www.npmjs.com/package/gl-matrix ↗

homepagehttps://glmatrix.net ↗