{"id":10949,"library":"gl-matrix","title":"glMatrix","description":"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.","status":"active","version":"3.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/toji/gl-matrix","tags":["javascript","typescript"],"install":[{"cmd":"npm install gl-matrix","lang":"bash","label":"npm"},{"cmd":"yarn add gl-matrix","lang":"bash","label":"yarn"},{"cmd":"pnpm add gl-matrix","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const mat4 = require('gl-matrix').mat4;","symbol":"mat4","correct":"import { mat4 } from 'gl-matrix';"},{"note":"Introduced in v3.0.0 for better tree-shaking and modularity. Individual modules export a namespace, so use `import * as Name from 'module/path'`.","wrong":"import { create } from 'gl-matrix/vec2';","symbol":"vec2 (cherry-picked module)","correct":"import * as vec2 from 'gl-matrix/vec2';"},{"note":"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.","wrong":"<script src=\"path/to/dist/gl-matrix.js\"></script>\n<script>\n  const matrix = mat4.create();\n</script>","symbol":"glMatrix (global object)","correct":"<script src=\"path/to/dist/gl-matrix.js\"></script>\n<script>\n  const matrix = glMatrix.mat4.create();\n</script>"},{"note":"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.","symbol":"Mat4 (TypeScript Type)","correct":"import type { mat4 as Mat4Type } from 'gl-matrix';"}],"quickstart":{"code":"import { mat4, vec3 } from 'gl-matrix';\n\n/**\n * Sets up a basic camera's projection and view matrices.\n * @param {mat4} projectionMatrix The matrix to store the projection results.\n * @param {mat4} viewMatrix The matrix to store the view results.\n * @param {number} aspectRatio The aspect ratio of the viewport (width / height).\n */\nfunction setupCamera(projectionMatrix: mat4, viewMatrix: mat4, aspectRatio: number): void {\n  // Create a perspective projection matrix (Field of View, Aspect, Near, Far)\n  mat4.perspective(projectionMatrix, Math.PI / 4, aspectRatio, 0.1, 100.0);\n\n  // Create a view matrix (camera position, target, up vector)\n  const cameraPosition = vec3.fromValues(0, 0, 5);\n  const target = vec3.fromValues(0, 0, 0);\n  const up = vec3.fromValues(0, 1, 0);\n  mat4.lookAt(viewMatrix, cameraPosition, target, up);\n\n  console.log('Initialized Projection Matrix:', projectionMatrix);\n  console.log('Initialized View Matrix:', viewMatrix);\n}\n\nconst projection = mat4.create();\nconst view = mat4.create();\nsetupCamera(projection, view, window.innerWidth / window.innerHeight);\n\n// Example: Create a model matrix for an object and apply transformations\nconst modelMatrix = mat4.create();\nconst translationVector = vec3.fromValues(1, 0.5, 0);\nmat4.translate(modelMatrix, modelMatrix, translationVector); // Translate by (1, 0.5, 0)\n\nconst rotationAxis = vec3.fromValues(0, 1, 0); // Rotate around Y axis\nmat4.rotate(modelMatrix, modelMatrix, Math.PI / 4, rotationAxis); // Rotate 45 degrees\n\nconsole.log('Model Matrix (translated and rotated):', modelMatrix);\n\n// To reset the matrix to identity:\nmat4.identity(modelMatrix);\nconsole.log('Model Matrix (reset to identity):', modelMatrix);","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=3.4.4"},{"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.","message":"In `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()`).","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version `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.","severity":"gotcha","affected_versions":"=3.4.0"},{"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.","message":"While 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<3.2.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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).","error":"ReferenceError: require is not defined"},{"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.","cause":"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).","error":"Uncaught ReferenceError: mat4 is not defined"},{"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).","cause":"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.","error":"Property 'create' does not exist on type 'typeof import(\"gl-matrix/dist/gl-matrix\")' or 'Type 'Float32Array' is not assignable to type 'number[]''"},{"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.","cause":"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.","error":"Error: Cannot use 'import.meta' outside a module"}],"ecosystem":"npm"}