API

A component is a self-mounting, reusable UI unit. Every component extends Component, which extends BaseComponent.

Constructing a component mounts its root element immediately, but does not render it — you must either register it in a parent via child registration or call render() yourself.

Override registerChildren() and match each entry's selector to a data-component mount point in your template:

Component has two independent mechanisms for feeding it data — pick based on whether the value drives template rendering, or a form field.

Every component inherits generateTemplate(): Nutin.Template (a string or an html result) from BaseComponent. render() calls it, sanitizes the result and inserts the resulting nodes into the component's element.

Dynamic rendering relies on events. You can also call .render() directly.

Mark an element data-optional, and it's removed after render if it (or its interpolated value) ends up empty. Only the rendering component's own elements are checked.

Write templates with the html tag. Every ${} in an html template is HTML-escaped, wherever the value comes from (an input, an HTTP response, localStorage, the server):

A view is the top-level orchestrator for a single route. Component and View are siblings - both extend BaseComponent.

A view is a routed page — one per route, mounted and destroyed by the router.

Route keys are path patterns — see How do I access route parameters? for the :id/:id? syntax.

The path's query string and #hash are kept. The path is always resolved on the current site: a path the app didn't write (e.g. from a ?next= parameter) can't send the browser to another host.

/posts/:id matches /posts/123 but not /posts. /users/:id? matches both /users and /users/123 — an unmatched optional param is simply absent from the params object, not present with an undefined value.

Guards receive the matched route params (not the raw path or query string), and run in array order, stopping at the first non-true result:

data-event="click:_handler" attributes in a template — local to one component/view, bound and rebound on every render, and torn down automatically in destroy().

eventName is bound via addEventListener to thishandlerMethodName. Listeners are rebound (old ones torn down first) on every render, and fully removed on destroy(). If eventName or handlerMethodName is empty, the attribute is ignored.

this.listen(event, callback) (available on every component/view) subscribes and automatically unsubscribes it on destroy. Prefer this over calling AppEventBus.subscribe directly, which has no automatic cleanup.

emit(event, data) is fire-and-forget and synchronous — it calls every current subscriber immediately, in registration order, and returns void. There's no queuing or async dispatch, so a subscriber added after emit() runs won't see that call. A subscriber that throws is logged with console.error, and the other subscribers still run. See How do I listen to application events? for subscribing.

All protected, all no-op by default except generateTemplate()/registerChildren():

A service holds state or logic that needs to stay consistent across the whole app, independent of any single component's or view's lifecycle. Every service extends the abstract Service<T> base class, which is a singleton — Nutin guarantees at most one instance of each service class exists.

Service<T> is an abstract singleton base. Calling new ExampleService() directly throws — getInstance() is the only valid way to construct one:

Import the exported singleton const, not the class:

registerCleanup(fn) is protected — call it from inside your own service (typically the constructor) to queue teardown logic. Override onDestroy() for teardown that needs to be async.

Call this once in main.ts, alongside registerPipes()/AppRouter(routes). Each entry's component is constructed and rendered internally, its root element's id is set to the entry's id, and:

Both look up document.getElementById(id) for each given id — the same id you passed to registerGlobals — and toggle only element.style.display. hideGlobals sets 'none', capturing the element's display value beforehand (its inline style.display, or the computed value if none was set) the first time that id is hidden. revealGlobals restores that captured value by default — pass display to override it with something else instead. Other inline styles are untouched, and a missing id is silently ignored (no throw, no warning).

data-pipe="pipeName[:arg1,arg2,...]" pipes an element's value/text through one or more registered pipes, writing the result back — .value for <input>/<textarea>, .textContent for anything else.

Registered by registerPipes(), which must be called once at bootstrap (in main.ts, before the first render) — none of these names resolve until then.

AppPipeRegistry is the singleton instance — it's the only public entry point (the underlying registry class isn't exported). Register your own pipes once at bootstrap, typically right after registerPipes() in main.ts, and they're immediately usable via data-pipe="slug".

AppHttpClient is the framework's default HttpClient singleton, without a base URL: a relative endpoint (/api/users) is resolved against the page's origin, and an absolute one (https://…) is used as it is. Only http: and https: URLs are accepted.