{"id":15229,"library":"regl","title":"regl: Fast Functional WebGL Framework","description":"regl is a fast, functional WebGL framework that simplifies graphics programming by abstracting the WebGL API into \"resources\" and \"commands.\" It emphasizes a data-flow approach, minimizing shared state to optimize performance. Instead of direct WebGL calls, developers define declarative commands describing the entire state for a draw call, which regl then compiles into optimized JavaScript. The current stable version is 2.1.1, last published a year ago as of November 2024. regl does not adhere to a strict release cadence, with updates occurring as needed for fixes and features. Its key differentiators include its functional paradigm, automatic state batching for performance, and a minimalistic API compared to raw WebGL, which appeals to users looking for a less verbose and more declarative approach to real-time graphics while maintaining high performance and stability.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/regl-project/regl","tags":["javascript","webgl","stackgl","regl","gl","graphics","computer graphics","opengl","glsl","typescript"],"install":[{"cmd":"npm install regl","lang":"bash","label":"npm"},{"cmd":"yarn add regl","lang":"bash","label":"yarn"},{"cmd":"pnpm add regl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default export is a factory function that creates the REGL instance. CommonJS examples often use `require('regl')()` directly.","wrong":"import { regl } from 'regl'; // Incorrect named import, it's a default export (factory)\nconst regl = require('regl'); // Missing function call to initialize","symbol":"regl","correct":"import createREGL from 'regl';\nconst regl = createREGL();"},{"note":"This is the prevalent usage pattern in older Node.js environments and many `regl` examples.","symbol":"regl (CommonJS)","correct":"const regl = require('regl')();"},{"note":"regl ships with TypeScript declarations. Use `import type` for type-only imports to avoid bundling issues and ensure correct type checking.","wrong":"import { REGL } from 'regl'; // Imports the runtime value, not just the type","symbol":"REGL (TypeScript Type)","correct":"import type { REGL, Buffer, Texture } from 'regl';"}],"quickstart":{"code":"const regl = require('regl')();\n\nconst drawTriangle = regl({\n  frag: `\n    precision mediump float;\n    uniform vec4 color;\n    void main() {\n      gl_FragColor = color;\n    }`,\n\n  vert: `\n    precision mediump float;\n    attribute vec2 position;\n    void main() {\n      gl_Position = vec4(position, 0, 1);\n    }`,\n\n  attributes: {\n    position: regl.buffer([\n      [-2, -2],\n      [4, -2],\n      [4, 4]\n    ])\n  },\n\n  uniforms: {\n    color: regl.prop('color')\n  },\n  count: 3\n});\n\nregl.frame(({time}) => {\n  regl.clear({\n    color: [0, 0, 0, 0],\n    depth: 1\n  });\n\n  drawTriangle({\n    color: [\n      Math.cos(time * 0.001),\n      Math.sin(time * 0.0008),\n      Math.cos(time * 0.003),\n      1\n    ]\n  });\n});","lang":"javascript","description":"This example initializes a full-screen WebGL context with regl and draws a single animating triangle, demonstrating core concepts like defining commands with shaders, attributes, and uniforms."},"warnings":[{"fix":"During development, ensure you compile or bundle with a debug flag (e.g., `--debug` for Browserify) to keep error messages and enable source maps. This helps catch issues faster.","message":"When developing with `regl`, especially when using tools like Browserify, runtime error messages and sanity checks are removed by default in production builds to reduce bundle size. This can make debugging difficult in deployed applications.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement a `webglcontextlost` event listener to call `event.preventDefault()` and a `webglcontextrestored` listener to systematically recreate and re-upload all necessary `regl` resources and re-evaluate commands.","message":"WebGL contexts can be lost by the browser due to various reasons (e.g., system resource constraints, GPU driver updates, switching GPUs). While `regl` includes basic context loss handling since v1.0.0, applications must be prepared to re-initialize all GPU-resident resources (textures, buffers, shaders) on a `webglcontextrestored` event.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Call the `.destroy()` method on `regl` resources (e.g., `regl.buffer(...).destroy()`, `regl.texture(...).destroy()`) once they are out of scope or no longer actively used, to free up GPU memory. Manage the lifecycle of these objects carefully.","message":"WebGL resources (buffers, textures, framebuffers, etc.) consume GPU memory. Failing to explicitly `destroy()` these resources when they are no longer needed can lead to memory leaks, especially in applications that frequently create and destroy dynamic content.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If migrating from very old `regl` code or referencing outdated examples, be aware that dynamic functions now expect `(context, props)` as their argument signature. Adjust function definitions accordingly.","message":"In `regl` versions prior to `0.6.0`, the order of arguments for dynamic functions was `(props, context)`. This was changed to `(context, props)` in `v0.6.0` to align with a more consistent pattern.","severity":"breaking","affected_versions":">=0.6.0 <1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Review the `frag` and `vert` shader strings for syntax errors, missing semicolons, incorrect variable declarations, or unsupported features. Check WebGL context version compatibility for specific GLSL features.","cause":"Invalid GLSL syntax or incompatible shader version for the WebGL context.","error":"GLSL shader compilation failed: ERROR: 0:1: 'precision' : syntax error"},{"fix":"Reload the browser tab or restart the browser. For programmatic handling, implement the context loss and restoration listeners described in the warnings.","cause":"The browser's WebGL context has been lost, often due to system resource exhaustion, GPU driver issues, or the browser moving the tab to a different GPU process.","error":"WebGL context lost. Unable to recover from software mode. Please restart your browser and reload the Viewer."},{"fix":"Ensure you call the imported `regl` factory function, typically as `const regl = require('regl')();` or `import createREGL from 'regl'; const regl = createREGL();`.","cause":"The `regl` module's default export is a factory function that needs to be called to instantiate the `REGL` object. This error occurs if `require('regl')` or `import createREGL from 'regl'` is used without immediately invoking it.","error":"TypeError: regl is not a function"}],"ecosystem":"npm"}