Hooks

A component's own hooks, such as mounted() and updated(), are about that one component (see Lifecycle). The hooks on this page are the runtime's: they run for every component, request and visit on the page, which is what analytics, error trackers, progress bars and your own plugins need.

Listening

Nitro.hook(name, listener) calls the listener each time the moment comes, and returns a function that removes it:

// Every request a component sends carries the current tenant.
Nitro.hook('beforeRequest', ({ headers }) => {
    headers['X-Tenant'] = document.body.dataset.tenant;
});

// A page view after each visit that went through.
Nitro.hook('afterNavigate', ({ url, cancelled }) => {
    if (!cancelled) plausible('pageview', { u: url });
});

// A hook() returns a function that removes the listener.
const stop = Nitro.hook('component.rendered', (component) => console.log(component.name, 'rendered'));
stop();

The hooks

The page

Components

A component is { name, el, dispatch(event, ...params) }. A listener of component.initialized added after the page started hears the components already there too.

Stores

A store is { name, persist, sync, get(property), values(), set(property, value), onChange(listener) }, its values as the server sends them. set() is a change made in the browser, which the server checks on the next call.

Requests

Navigation

Messages

Stopping a request or a visit

A beforeRequest or beforeNavigate listener can call preventDefault() to stop what is about to happen. A stopped #[Server] call sends nothing and resolves with null; what changed in the browser stays, and goes with the next call. A stopped upload fires nitro-upload-cancel on its input.

// Ask before leaving a page with changes the server hasn't seen yet.
Nitro.hook('beforeNavigate', (visit) => {
    const unsaved = Nitro.components().some((component) => component.unsaved().length > 0);

    if (unsaved && visit.cancelable && !confirm('You have unsaved changes. Leave this page?')) {
        visit.preventDefault();
    }
});

Back and forward can't be stopped: by the time the visit starts, the browser has already changed the address. Their beforeNavigate has cancelable: false, and preventDefault() does nothing there.

// Offline: hold #[Server] calls back and say so. What changed stays, and goes with the next call.
Nitro.hook('beforeRequest', (request) => {
    if (request.kind === 'call' && !navigator.onLine) {
        request.preventDefault();
        showToast('You are offline. Your changes are kept and will be saved when you are back.');
    }
});

• Every before has its after. A stopped request or visit still gets its afterRequest or afterNavigate, with cancelled: true, so a counter of what's in flight, such as a progress bar, stays right.
• The order. Listeners run in the order they were added. One added earlier hears a moment even when a later one stops it, which is why the after always comes.

Before Nitro is on the page

Nitro.hook() needs Nitro. A script that loads before @nitroScripts, such as a module in the <head>, waits for nitro:init on the document instead, which comes with Nitro just before any component starts. See Running code before components start.

Window events

Most hooks also dispatch an event, with the same details in event.detail and the component by its name. It suits code that only listens, such as a widget that knows nothing of Nitro. A stoppable hook's event can be stopped with event.preventDefault() as well.

The earlier names are still sent through 2.x, so code written for them keeps working. They can't be stopped, as they never could.

In a plugin

A plugin's on(name, listener) is Nitro.hook(), so a plugin listens to the same hooks. The names plugins used before, component, render, store, request and response, still work. See Writing plugins.

When a listener fails

A listener that throws is reported, as the error hook and in the console, and the other listeners still run. A listener of error itself that throws only goes to the console, so a broken error tracker can't loop.

Next steps