Dependencies Required to Run Matter.js

This article explains the runtime requirements and optional dependencies needed to use Matter.js in web and server-side environments. While Matter.js is fundamentally a standalone, zero-dependency 2D physics engine, certain advanced features and platform-specific implementations rely on optional external libraries and environment-specific APIs to function properly.

Core Engine Dependencies

The core Matter.js engine has zero external runtime dependencies. It is packaged as a completely self-contained JavaScript library. To run basic rigid body simulations, collision detection, and constraint resolution, you only need an environment capable of executing modern JavaScript (ECMAScript 5 or higher).

Environment Requirements

• Web Browsers: Matter.js works natively in all modern web browsers (Chrome, Firefox, Safari, Edge). If you use the built-in Matter.Render module for visualization, the browser must support the HTML5 <canvas> element. However, the physics engine can run completely headless if you choose to visualize bodies using third-party renderers such as Pixi.js or Three.js.
• Node.js: To run Matter.js in a server-side or headless environment, any active LTS release of Node.js is sufficient. No additional system packages or native C++ compilation tools (such as node-gyp) are required.

Optional Dependencies for Advanced Features

While the engine does not require dependencies for standard primitives (rectangles, circles, and convex polygons), two external libraries are required for specialized geometry:

• poly-decomp: Matter.js only supports convex polygons natively. If you need to create concave bodies using Bodies.fromVertices, you must provide the poly-decomp library. You must install it and assign it globally or pass it into Matter.js before decomposing complex shapes.
• pathseg polyfill: If you generate physics bodies from SVG paths using Vertices.fromPath, modern browsers require a polyfill for the deprecated SVGPathSeg API (such as pathseg.js). Modern rendering engines have removed this native API, making the polyfill mandatory when parsing raw SVG path data.