{"id":15158,"library":"ogl-typescript","title":"OGL-TypeScript","description":"OGL-TypeScript is a comprehensive TypeScript port of the minimal WebGL library, OGL, designed to enhance development with robust type definitions and essential code completion. Currently stable at version 0.1.40, it meticulously tracks the releases and API changes of its upstream counterpart, OGL (currently mirroring OGL 0.0.71). The library's core focus is to provide a lightweight and unopinionated foundation for building high-performance 3D graphics directly with WebGL in the browser. Its key differentiators include a significantly small bundle size, direct and low-level access to WebGL APIs, and the added benefit of TypeScript's type safety, which makes managing complex WebGL shaders and rendering pipelines more efficient and less prone to runtime errors compared to plain JavaScript OGL. The release cadence is tightly coupled with OGL's updates, typically seeing new minor versions released to align with new OGL features, fixes, or API refinements.","status":"active","version":"0.1.40","language":"javascript","source_language":"en","source_url":"https://github.com/nshen/ogl-typescript","tags":["javascript","webgl","ogl","ogl-typescript","typescript"],"install":[{"cmd":"npm install ogl-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add ogl-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add ogl-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"OGL-TypeScript is designed for ESM; CommonJS `require` syntax is generally not supported for individual named exports in modern setups, leading to potential issues.","wrong":"const Renderer = require('ogl-typescript').Renderer","symbol":"Renderer","correct":"import { Renderer } from 'ogl-typescript'"},{"note":"All core components like Camera are named exports, not default exports. Attempting a default import will result in an error.","wrong":"import Camera from 'ogl-typescript'","symbol":"Camera","correct":"import { Camera } from 'ogl-typescript'"},{"note":"Ensure you are importing from 'ogl-typescript' and not the original 'ogl' package to benefit from TypeScript types and the ported codebase.","wrong":"import { Mesh } from 'ogl'","symbol":"Mesh","correct":"import { Mesh, Program, Geometry } from 'ogl-typescript'"}],"quickstart":{"code":"import { Renderer, Camera, Transform, Program, Geometry, Mesh } from 'ogl-typescript';\n\n// 1. Setup Renderer\nconst renderer = new Renderer({\n    canvas: document.createElement('canvas'),\n    width: window.innerWidth,\n    height: window.innerHeight,\n    dpr: Math.min(window.devicePixelRatio, 2),\n});\ndocument.body.appendChild(renderer.canvas);\n\n// 2. Setup Camera\nconst camera = new Camera({ fov: 45 });\ncamera.position.set(0, 0, 5);\ncamera.lookAt([0, 0, 0]);\n\n// 3. Create a Scene (as a Transform) to hold objects\nconst scene = new Transform();\n\n// 4. Create Geometry (a simple plane)\nconst geometry = new Geometry(renderer.gl, {\n    position: {\n        size: 3,\n        data: new Float32Array([\n            -1, 1, 0, // Top-left\n            -1, -1, 0, // Bottom-left\n            1, -1, 0, // Bottom-right\n            1, 1, 0, // Top-right\n        ]),\n    },\n    uv: {\n        size: 2,\n        data: new Float32Array([\n            0, 1,\n            0, 0,\n            1, 0,\n            1, 1,\n        ]),\n    },\n    index: {\n        data: new Uint16Array([\n            0, 1, 2,\n            0, 2, 3,\n        ]),\n    },\n});\n\n// 5. Create a basic Program (shader) to define material properties\nconst program = new Program(renderer.gl, {\n    vertex: /* glsl */ `\n        attribute vec3 position;\n        attribute vec2 uv;\n\n        uniform mat4 modelViewMatrix;\n        uniform mat4 projectionMatrix;\n\n        varying vec2 vUv;\n\n        void main() {\n            vUv = uv;\n            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n        }\n    `,\n    fragment: /* glsl */ `\n        precision highp float;\n\n        varying vec2 vUv;\n\n        void main() {\n            gl_FragColor = vec4(vUv.x, vUv.y, 0.5, 1.0);\n        }\n    `,\n});\n\n// 6. Create a Mesh by combining geometry and program, then add to scene\nconst mesh = new Mesh(renderer.gl, { geometry, program });\nmesh.setParent(scene);\n\n// 7. Render Loop for animation\nfunction update() {\n    requestAnimationFrame(update);\n\n    // Rotate the mesh for visual interest\n    mesh.rotation.y -= 0.005;\n    mesh.rotation.x -= 0.003;\n\n    renderer.render({ scene, camera });\n}\nrequestAnimationFrame(update);\n\n// Basic resize handling to keep aspect ratio correct\nwindow.addEventListener('resize', () => {\n    renderer.setSize(window.innerWidth, window.innerHeight);\n    camera.perspective({ aspect: window.innerWidth / window.innerHeight });\n});","lang":"typescript","description":"This quickstart initializes a WebGL renderer, sets up a camera, creates a simple 3D plane geometry, defines a basic shader program, and renders a spinning mesh on a canvas, demonstrating core OGL-TypeScript usage."},"warnings":[{"fix":"Always consult the release notes of the corresponding OGL version that ogl-typescript mirrors (as listed in the versions table in the README) for details on API changes and migration steps when updating.","message":"OGL-TypeScript acts as a direct port of the original OGL library. Consequently, any API changes or breaking updates introduced in upstream OGL versions will directly propagate to ogl-typescript, often leading to breaking changes in minor versions (e.g., 0.1.x).","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure the HTML canvas element is correctly created and appended to the DOM before initializing the Renderer. Verify `renderer.gl` is a valid WebGLRenderingContext after instantiation to confirm context creation.","message":"Incorrect or delayed WebGL context initialization, or improper canvas element handling, can lead to rendering failures or errors like 'Cannot read properties of undefined (reading 'getContext')'.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Thoroughly review your vertex and fragment shader code for GLSL syntax correctness. Utilize browser developer tools (e.g., Chrome's 'WebGL' tab) for detailed shader compilation logs and error messages.","message":"Shader compilation errors in the `Program` constructor are common. Issues often stem from GLSL syntax mistakes, undeclared uniforms/attributes, or type mismatches within the shaders.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `document.createElement('canvas')` successfully creates an element and it's appended to the DOM, or pass an existing, valid canvas element (e.g., `canvas: document.getElementById('my-canvas')`).","cause":"The `Renderer` constructor was called without a valid HTMLCanvasElement, or the provided canvas was null/undefined, preventing WebGL context creation.","error":"TypeError: Cannot read properties of undefined (reading 'getContext')"},{"fix":"Review the `ogl-typescript` type definitions or documentation (or the original OGL documentation) to verify the correct symbol name and its export status. Ensure case sensitivity is respected.","cause":"Attempting to import a named symbol that does not exist or is misspelled within the `ogl-typescript` package, or it was renamed in a new version.","error":"SyntaxError: The requested module 'ogl-typescript' does not provide an export named 'SomeMissingExport'"},{"fix":"Check the version compatibility between your `ogl-typescript` package and the corresponding OGL version's API documentation. Update your code to reflect the current API, or consider upgrading `ogl-typescript` if the feature was added recently.","cause":"A TypeScript compilation error indicating that an accessed property or method is not part of the expected type, often due to an API change in the underlying OGL library that `ogl-typescript` ports, or incorrect usage.","error":"Property 'someProperty' does not exist on type '...' (TypeScript error)"}],"ecosystem":"npm"}