How shuding/cobe works
Project type and purpose
• This is a JavaScript/TypeScript monorepo containing:
• A lightweight WebGL “globe” rendering library (“cobe”)
• A Next.js-based static documentation & demo website
• Purpose: provide a 5 KB globe-rendering library (with shaders, texture loader, animation loop) and a site with MDX-based docs, examples, and playground.
File structure
• Top-level files and directories:
• package.json, pnpm-lock.yaml, pnpm-workspace.yaml – monorepo configuration
• tsconfig.json – TypeScript definitions for the library
• scripts/build.js – build script (invokes glslx, bundles shaders into JS)
• src/ – library source:
– index.js / index.d.ts – public API (createGlobe)
– shader.frag – GLSL fragment shader
– texture.js – image/texture loader
• website/ – Next.js documentation site:
– pages/ – MDX pages for docs, showcases, playground
– theme.config.js, toColor.js – site theming & utilities
– next.config.js, package.json, pnpm-lock.yaml – site build config
README for additional insights
• Describes public API (createGlobe(canvas, options)) and parameters
• Mentions external dependencies: Phenomenon (animation loop), glslx (shader transpiler), world-map asset
• Shows usage examples for React, Vue3, Svelte, vanilla JS
a. Main components
1. Build Pipeline
– scripts/build.js
– glslx (shader → JS)
– bundler (rollup/webpack via package.json scripts)
2. Library Core
– src/index.js (public API)
– shader.frag (rendering logic)
– src/texture.js (texture loader)
– Phenomenon instance (animation frame manager)
3. Package Registry
– npm (published “cobe” package)
4. Documentation Website
– Next.js frontend
– MDX content (pages/docs, showcases, playground)
– React components, theme.config, toColor.js
5. End-Users
– Any web app (React/Vue/Svelte/vanilla) importing “cobe”
6. External Assets & Services
– World map SVG (imported at build time)
– Vercel (deployment of website)
b. Relationships and interactions
– Build Pipeline produces the “cobe” package → published to npm
– Website and external consumers pull “cobe” from npm
– Consumer app calls createGlobe() → initializes WebGL context → loads texture → compiles & runs shader code → hands control to Phenomenon for animation loop
– Website build statically generates pages (Next.js SSG/SSR) embedding live globe demos
c. Architectural patterns & design principles
– Monorepo / workspace to co-locate library and docs
– Clear separation of concerns:
• Build scripts vs. library runtime
• Library core vs. website consumer
– Plugin/extension points: users supply onRender callback, markers array
– Pipeline pattern: shader transpilation → bundling → package → consumption
d. Relevant technologies & frameworks
– Node.js, pnpm workspace
– glslx (GLSL to JS transpiler)
– Phenomenon (animation manager)
– WebGL (fragment shader, texture sampling)
– Next.js + MDX (docs site)
– Vercel for hosting