cobe

Cobe renders an interactive 3D globe directly onto an HTML canvas using raw WebGL2 (with a WebGL1 + ANGLE_instanced_arrays fallback for older browsers), with no runtime dependencies and a published bundle of roughly 5KB. Its shaders are authored in the GLSLX shading language and precompiled at build time, so the published package ships plain, minified GLSL rather than compiling shaders from source at runtime.

The API is a single createGlobe(canvas, opts) call that returns update() and destroy() functions, letting consumers drive rotation, markers, arcs, and colors imperatively — a pattern documented in the README for React’s requestAnimationFrame loops. Version 2 adds arcs connecting two globe locations and CSS Anchor Positioning support, so markers and arcs can be bound to ordinary DOM elements (tooltips, labels) via CSS custom properties instead of manual screen-space projection math.

What You Get

• A single createGlobe(canvas, opts) function that renders directly onto a <canvas> using WebGL2 (falling back to WebGL1 with the ANGLE_instanced_arrays extension, and a manual per-instance draw loop as a last resort)
• An update(state) method that applies a Partial<COBEOptions> patch — rotation (phi/theta), markers, arcs, colors, opacity, scale, and canvas size — and re-renders without recreating the WebGL context
• Shaders precompiled from GLSLX source (.glslx files) into plain GLSL at build time via scripts/build.js, so no shader-language compilation happens in the browser
• CSS Anchor Positioning hooks — markers and arcs with an id expose --cobe-{id} / --cobe-visible-{id} CSS custom properties so ordinary DOM elements can be pinned to their screen position purely in CSS

Common Use Cases

• Visualizing a global user or customer base on marketing and landing pages
• Rendering live geographic data points on analytics or status dashboards
• Drawing flight paths, network links, or shipment routes as arcs between coordinates
• Embedding an interactive globe without the bundle weight of a full 3D/mapping library

Under The Hood

Architecture The entire rendering pipeline lives behind a single default export, createGlobe(canvas, opts) in src/index.js, which creates the WebGL context, compiles three shader programs (globe, marker, arc) via the small webgl.js helper module, sets up quad/instance buffers, and returns a closure exposing update() and destroy(). All mutable state (phi, theta, markers, arcs, colors, scale) is captured as local variables inside that closure rather than passed through any store or class instance, and update() merges partial state then immediately re-issues a three-pass draw sequence (globe quad, instanced arcs, instanced markers) using WebGL2 instancing or the ANGLE_instanced_arrays extension. DOM/CSS integration is factored into a separate anchor.js module (createAnchorManager) that tracks marker/arc anchor <div> elements and a single shared <style> tag for CSS custom properties, avoiding a per-frame stylesheet rewrite unless visible markers actually change. The design is a modular monolith: one large orchestrating file plus small, single-purpose helpers (webgl.js, anchor.js, texture.js); replacing the core createGlobe closure would mean replacing the whole rendering pipeline, since there is no dependency injection or plugin seam.

Tech Stack The library is hand-written JavaScript with JSDoc type annotations rather than TypeScript, publishing type declarations only through a separately maintained index.d.ts. It has zero runtime dependencies and targets the browser’s native WebGL2/WebGL1 APIs directly. The build pipeline uses esbuild for JS bundling, the glslx compiler to turn .glslx shader source into minified GLSL string constants injected at build time, and terser for a final minification pass beyond what esbuild alone achieves, in service of keeping the published bundle near 5KB. The package is ESM-only (type: module) and lives in a pnpm workspace alongside a separate website/ Next.js 12 + React 18 demo app that is not part of the published package.

Code Quality No test files exist anywhere in the repository — there is no *.test.*, *.spec.*, or test directory, and correctness appears to rely on manual verification against the interactive demo site. Source files use consistent JSDoc-annotated plain JavaScript; failure paths (missing WebGL context, failed shader/program compilation) return no-op { update, destroy } objects rather than throwing, which is defensive but silent about failures. No linter, formatter, or CI configuration is present in the cloned repository.

API Design The public surface is intentionally minimal: one default export, createGlobe(canvas, opts), returning { update, destroy }, with nearly every visual option defaulted via ||/?? fallbacks so a consumer can start from a handful of required fields and opt into the rest incrementally. update() accepting a Partial<COBEOptions> patch is a deliberate fit for framework render loops (the README shows a React requestAnimationFrame pattern that increments phi every frame). The CSS Anchor Positioning integration in v2 — binding marker/arc ids to --cobe-{id} custom properties — is a genuinely distinctive DX choice, letting consumers position DOM tooltips relative to 3D globe points without any manual projection math on their side. Documentation is limited to the README’s Quick Start, Arcs, and Bindable Markers sections, with no separate docs site beyond the live demo.