# LumenJS

> LumenJS is a tiny, no-virtual-DOM reactive framework for building
> single-page apps with standard HTML, CSS and JavaScript. You write `.view`
> files (plain HTML+JS+CSS) with no build configuration: `lm serve`
> interprets them live, and `lm build` precompiles them into one bundle that
> renders without a parser. It pairs with MobiusCSS for layout utilities and
> the Roxyon BaaS for the backend. Current version: V2, release 2.5.3
> (`@lmjs/cli` + `@lmjs/core`).

## Read first

- [Complete LumenJS V2 reference](https://lumenjs.com/llms/lumenjs.txt) (same file as [Markdown](https://lumenjs.com/llms/lumenjs.md)): the whole framework, contrasted with Vue/React. Read it before writing any `.view` file. Do not mix V1 idioms into V2 code, especially `bind=`, `comp=` and the `session` global.
- Data access and the Roxyon BaaS query DSL: sections 10 and 10b of the reference above.

## The rules that bite (V2)

- Any top-level `var`/`let`/`const` in a view's `<script>` (or in `index.js`/a project script) is automatically reactive. There is no `bind=` in V2.
- A function call in a `{{ }}` moustache is evaluated when its block renders and is not re-run when the data it reads changes. Keep the value in a reactive variable, or interpolate the data directly.
- A `{{ }}` value that looks like HTML markup is rendered as HTML. Escape untrusted strings yourself.
- `:for` loops nest, and loop variables work directly in attributes, including on the looping element itself.
- Attribute order is priority: `<i :if="show" :for="xs as x">` gates the whole loop; `<i :for="xs as x" :if="x.on">` filters rows.
- `tpl="name"` works only on a `:for` element and renders once per row in that row's scope. `comp=` was removed in 2.4.1 and renders nothing. Use `view=` + `@init` when a row needs its own state.
- Every mounted instance of the same subview (`view="..."`) has its own isolated variables. Pass data in at mount with `@init`, not `:data=`.
- A DOM-owning plugin inside a `:for`/`:if` needs `@after-render` to reinitialize after a re-render replaces its DOM.
- Forms are handled wholesale via `o-sub` / `b-sub` on the `<form>`; there is no `v-model`.
- No `session` global: use `sessionStorage` directly. `globals` persists to `localStorage`.
- `wait()` / `resume()` only pause and resume rendering. The loader is shown and hidden by your own code (`_loader.show()` / `_loader.hide()`).
- A bare `stop` attribute stops event propagation for every handler on that element.
- Never put a raw API secret in `config.json`. Use `lm login` + `lm api set <name>` (the vault) instead; the value never touches a local file.

## Tooling

- [@lmjs/cli](https://www.npmjs.com/package/@lmjs/cli) / [@lmjs/core](https://www.npmjs.com/package/@lmjs/core): `npm i -g @lmjs/cli`, then `lm create <name>`, `lm serve`, `lm build`.
- **Each project ships its own runtime, `src/js/lm.js`.** After upgrading the CLI, run `lm update-core` before building. 2.5.1+ builds need `EXPECTED_HST_FORMAT_VERSION=3` in that file. Since 2.5.3 the build stops on an older runtime (before, it only warned and the site broke).
- Pin a version without a global install: `npx -y -p @lmjs/cli@2.5.3 lm <command>`.
- Need real jQuery + a plugin (Select2, Flickity, ...)? List it in the project's own `package.json` `dependencies`; only what you list is bundled.
- Real npm imports work in `index.js`/project scripts (`npm install`, then `import`), resolved at build time.
- Deploy: `lm build --serverless --deploy` uploads `dist/` over SFTP/FTP using `config.json`'s `ftp` block. Plain `lm build` produces a self-hosting Node server bundle instead.

## Also available as

- https://lumenjs.com/lm.txt (same content as this file)