Lumen

A transparent, no-magic, no-build vanilla-JS OOP UI framework. What you write is what runs.

Un framework de UI en JS vanilla, OOP, transparente, sin magia y sin build. Lo que escribes es lo que corre.

📖 Live docs & examples · Documentación y ejemplos en vivo: https://dragones-tech.github.io/lumen/site/

Install · Instalar

No build, native ES modules, zero runtime deps. Full guide: en · es.

<!-- 1) CDN, no install — import map + jsDelivr (pin a tag/commit for production) -->
<script type="importmap">
{ "imports": {
  "lumenjs": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/index.js",
  "lumenjs/": "https://cdn.jsdelivr.net/gh/dragones-tech/lumen@main/src/"
}}
</script>
<script type="module">
  import { View } from 'lumenjs';
</script>

# 2) or copy src/ into your project (most transparent)
# 3) or npm:
npm i @jehosogo/lumenjs                    # published on npm
# or from GitHub: npm i github:dragones-tech/lumen

Principles · Principios

• No build. Native ES modules. The only thing you need is a static file server (ES module imports are blocked on file://). Your .js reaches the browser untouched.
• No magic. No global side effects on import, no hidden proxies, no compiler rewriting your code. Explicit OOP with a lifecycle you can read.
• No Web Components. Plain classes (not extends HTMLElement), so you keep full control of animate/unmount. A Custom Element adapter is an opt-in escape hatch.
• Separate HTML. Markup lives in native <template> elements — real HTML, full editor autocomplete.
• Style-agnostic. Ships zero CSS. Bring plain CSS, native @scope, Tailwind — whatever you like.
• Typed without a build. Plain .js + JSDoc types, checked with tsc --noEmit.

Run the examples · Correr los ejemplos

# from the repo root — zero-dep Node static server with live reload
npm run serve   # save a file → the browser reloads (set LIVERELOAD=0 to disable)
# then open http://localhost:8000/examples/event-emitter/

Docs site · Sitio de docs

A bilingual (EN/ES) documentation site built with Lumen itself — sidebar + router + each page's live example embedded. Un sitio de documentación bilingüe hecho con Lumen.

npm run serve
# open http://localhost:8000/site/

Type-check · Verificar tipos

npm install   # dev-only: TypeScript, for checking JSDoc types (never runs in the browser)
npm run check

Modules · Módulos

| Module | Status | Docs | |---|---|---| | event-emitter | ✅ done | en · es | | dom | ✅ done | en · es | | animate | ✅ done | en · es | | view | ✅ done | en · es — abstract base class you extend | | model | ✅ done | en · es | | collection | ✅ done | en · es | | collection-view | ✅ done | en · es | | region | ✅ done | en · es | | router | ✅ done | en · es | | http | ✅ done | en · es — fetch wrapper | | i18n | ✅ done | en · es — translations | | validate | ✅ done | en · es — model + UI validation | | element | ✅ done | en · es — use a View as a Custom Element (defineElement) | | canvas | 🧪 experimental | en · es — render the same Model/Collection to canvas (Stage/Node2D/CanvasLayer); import from lumenjs/canvas |

Guides · Guías

• Styling (Lumen is style-agnostic; plain CSS, @scope, Tailwind): en · es — runnable Tailwind example.
• Deployment & loading (HTTP/2, import maps, modulepreload — no bundler needed): en · es.
• For AI agents (llms.txt, AGENTS.md): en · es.
• Credits & lineage (homage to Backbone & Marionette): en · es.

For AI agents · Para agentes de IA

Machine-readable docs so an assistant (Claude, Codex, Cursor…) writes idiomatic Lumen:

• llms.txt — index of all docs (llmstxt.org convention).
• llms-full.txt — every page in one file; paste it into your assistant.
• AGENTS.md — project conventions for coding agents (and CLAUDE.md for Claude Code).

Regenerate the llms.* files after editing docs with npm run llms.

Credits · Créditos

Lumen is a respectful, modernized homage to Backbone.js (Model, Collection, events-first) and Marionette.js (View, Region, CollectionView, layouts). The patterns are theirs; the implementation is rebuilt on the modern platform — no jQuery, no Underscore, no build. No Backbone/Marionette code is used; these are conceptual inspirations. See credits.