Overview

import { utils } from "mates" is a one-level proxy into the window MatesUtils store that renderApp creates. utils.pathAtom is the real atom; methods like utils.navigateTo are bound. The proxy itself holds no per-request state — each access looks the store up.

After renderApp, utils works inside components and outside them (fetch handlers, timers). useUtils() still works and returns the same instance; prefer utils when you are not in a component outer function.

Do not import pathAtom, themeAtom, or lsStore as module globals. Nested: utils.router is the same RouterUtils instance behind pathAtom / navigateTo. Storage and theme pages cover those bags in depth.

vs custom scope

API
Lifetime
Prefer when
utils / useUtils() one per window Router, fetch, storage, theme — created by renderApp.
scope(MyClass) subtree Feature UI state shared parent→descendants.

Read chrome from utils

pathAtom, themeAtom, titleAtom, and lsStore are all on the same MatesUtils instance.

import { html, utils, renderApp } from 'mates';

const App = () => {
return () => html`
<div class="m-col m-gap">
<p class="muted m-t-5">path=${utils.pathAtom()}</p>
<p class="muted m-t-5">theme=${utils.themeAtom()} · title=${utils.titleAtom()}</p>
<p class="muted m-t-5">lsStore=${utils.lsStore() == null ? 'null' : 'object'}</p>
<button class="btn-primary" @click=${() => utils.themeAtom.toggle()}>toggle theme</button>
</div>
`;
};
renderApp(App, document.getElementById('app'));

navigateTo outside a component

After renderApp, a module-level helper can call utils.navigateTo — pathAtom stays in sync.

import { html, utils, renderApp } from 'mates';

// After renderApp, utils works outside components too (timers, fetch handlers).
function go(path) {
utils.navigateTo(path);
}

const App = () => {
return () => html`
<div class="m-col m-gap">
<p class="muted">${utils.pathAtom()}</p>
<p class="muted m-t-5">location.path=${utils.location.path}</p>
<div class="m-flex m-items-center m-justify-center m-gap-sm">
<button class="btn-primary" @click=${() => go('/docs')}>/docs</button>
<button @click=${() => go('/docs/state')}>/docs/state</button>
</div>
</div>
`;
};
renderApp(App, document.getElementById('app'));