`tosijs` keeps the state of a web app in plain objects and wires it to real DOM elements.
Change the state and the elements bound to it update, with no virtual DOM, no JSX and no
build step. It is small enough to read in an afternoon.
```
npm install tosijs # or: bun add tosijs
```
```
import { tosi, elements } from 'tosijs'
const { app } = tosi({ app: { name: 'world' } })
const { h1, input } = elements
document.body.append(
h1('Hello, ', app.name),
input({ bindValue: app.name })
)
```
No build step at all? The same code runs from a CDN in a module script:
```
```
**New here? [Start Here](https://tosijs.net/start-here/)** is a ten-minute tutorial on the
two tools everything else is built on: the observer proxy and element creators. [Building Apps](https://tosijs.net/Building-Apps/)
is the full guide.
## Principles
A web page is a set of visible things (**elements**) on a screen, showing information
(**data**). An app differs from a static page in one way: the data can change.
`tosijs` is built on three principles that follow from that:
1. **The browser is incredible. Let it do what it does best.** HTML, the DOM, CSS, real
events and standard ``s with their native accessibility are the platform, not
something to re-implement.
2. **Elements are the user interface.** Creating them, fine-tuning them and updating
them should be insanely easy. That is what
[element creators](https://tosijs.net/elements/) are for.
3. **State is why the app exists.** Maintaining it, updating it from what the user does
and from what happens elsewhere, and showing every change to the user quickly and
accurately should be insanely easy. That is what the
[observer proxy](https://tosijs.net/xin/) is for.
And one about you: **what you already know about the browser is leveraged, not set
aside.** The more you know about what goes on behind the scenes, the better you will be
with `tosijs`; the less you know, the less you will have to learn that is not universally
true and useful. There is no framework-shaped replacement for the platform to learn, and
re-learn at every major version.
## Better apps with less code
Less code to **write, read, run, debug, and maintain** — which, as a bonus in the
age of AI assistants, also means **fewer tokens** to generate and reason about.
What the principles buy you:
- **O(~1) DOM updates, even for big lists.** A state change surgically updates exactly
the bound nodes — no virtual DOM, no diffing, no re-render-the-world. And because
virtual list bindings are built in, a 100,000-row list only ever renders (and
updates) the handful of rows actually on screen. (Give the list `virtual` and a
container that scrolls; an unvirtualized list of more than 10 items warns. See
[Array Bindings](https://tosijs.net/list-binding/).)
- **No JSX, no transpilation, no build step required.** Pure JS/TS in, native DOM
nodes out — works in plain JavaScript or TypeScript.
- **No lock-in.** State is a plain observable object graph, not a framework you
marry; bind it to vanilla DOM, web-components, React, or Angular.
- **Zero runtime dependencies.**
~30 kB gzipped from a script tag, ~28 kB for `tosijs/core`, ~18 kB for the
DOM-free `tosijs/state`; the full ESM entry is ~47 kB.
The agent surface is opt-in and shakes away if you never import it. It costs
~16.7 kB — the marginal measurement,
the same ESM bundle built with and without it — including the schematic
renderer, the accessibility audit and the contract harnesses. (The gap
between `tosijs` and `tosijs/core` is a larger
~19.0 kB, because `core` also drops blueprints,
share/sync and hotReload.) Both figures are measured by the build.
[Entry points](#entry-points) has the detail.
On top of that you get the conveniences you'd actually want: most binding code
eliminated, web-components you can build in pure JS more compactly than JSX, and
CSS handled with variables and real `Color` math.
```js
import { elements, tosi, touch, deleteListItem } from 'tosijs'
const todo = {
list: [],
addItem(reminder) {
if (reminder.trim()) {
todo.list.push({ id: Math.random(), reminder })
}
},
}
todo.addItem('wash the cat')
todo.addItem('buy milk')
const { readmeTodoDemo } = tosi({ readmeTodoDemo: todo })
const { h4, ul, label, input } = elements
preview.append(
h4('To Do List'),
ul(
...readmeTodoDemo.list.tosi.listBinding(
({ li, button }, item) =>
li(
item.reminder,
button('Done!', {
style: {
marginLeft: 10,
},
onClick(event) {
// deleteListItem resolves the row from any child node — pass the
// button and it walks up to find its list item automatically
deleteListItem(event.target)
},
})
),
{ idPath: 'id' }
)
),
label(
'Reminder',
input({
placeholder: 'enter a reminder',
onKeydown(event) {
if (event.key === 'Enter') {
event.preventDefault()
readmeTodoDemo.addItem(event.target.value)
event.target.value = ''
// addItem() pushed onto the original array, not through the proxy,
// so tell tosijs it changed (a write through the proxy needs no touch)
touch(readmeTodoDemo)
}
},
})
)
)
```
In general, `tosijs` is able to accomplish the same or better compactness, expressiveness,
and simplicity as you get with highly-refined React-centric toolchains, but without transpilation,
domain-specific-languages, or other tricks that provide "convenience" at the cost of becoming locked-in
to React, a specific state-management system (which permeates your business logic), and usually a specific UI framework.
`tosijs` lets you work with pure HTML and web-components as cleanly—more cleanly—and efficiently than
React toolchains let you work with JSX.
export default function App() {
return (
Hello React
Start editing to see some magic happen!
);
}
Becomes:
const { div, h1, h2 } = elements // exported from tosijs
export const App = () => div(
{ class: 'App' },
h1('Hello tosijs'),
h2('Start editing to see some magic happen!')
)
Except this reusable component outputs native DOM nodes. No transpilation, spooky magic at a distance,
or virtual DOM required. And it all works just as well with web-components. This is what you get when
you run App() in the console:
▼
Hello tosijs
Start editing to see some magic happen!
The ▼ is there to show that's **DOM nodes**, not HTML.
`tosijs` lets you lean into web-standards and native browser functionality while writing less code that's
easier to run, debug, deploy, and maintain. Bind data direct to standard input elements—without having
to fight their basic behavior—and now you're using _native_ functionality with _deep accessibility_ support
as opposed to whatever the folks who wrote the library you're using have gotten around to implementing.
> **Aside**: `tosijs` will also probably work perfectly well with `Angular`, `Vue`, et al, but I haven't
> bothered digging into it and don't want to deal with `ngZone` stuff unless someone is paying
> me.
If you want to build your own `web-components` versus use something off-the-rack like
[Shoelace](https://shoelace.style), `tosijs` offers a `Component` base class that, along with
its `elements` and `css` libraries allows you to implement component views in pure Javascript
more compactly than with `jsx` (and without a virtual DOM).
import { Component, elements, css } from 'tosijs'
const { h1, slot } = elements
export class MyComponent extends Component {
static shadowStyleSpec = css({
h1: {
color: 'blue'
}
})
content = [ h1('hello world'), slot() ]
}
Give a component attributes with `withAttributes()` — `class MyCard extends
withAttributes({ caption: '' }) {}` — so they are typed on `this`. Since 1.10.0
`Component` has no index signature, so an undeclared `this.caption` is a type
error rather than a silent `any`. `static initAttributes` is not deprecated; see
[Migration](https://tosijs.net/Migration/) for both forms.
The difference is that `web-components` are drop-in replacements for standard HTML elements
and interoperate happily with one-another and other libraries, load asynchronously,
and are natively supported by all modern browsers.
## Entry points
| import | what you get | gz |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
| `tosijs` | everything, agent surface included — bundlers shake what you don't import | ~47 kB |
| `tosijs/agent` | the agent surface, schematic renderer, audit and contract harnesses (**same file**, narrower types) — **EXPERIMENTAL** | — |
| `tosijs/core` | no blueprint loader, no `share`/`sync`/`hotReload`, no agent surface | ~28 kB |
| `tosijs/state` | the **DOM-free** state layer: `tosi`, `observe`, `touch`, paths | ~18 kB |
| `
