Avenx-JS components go through a structured series of initialization, mounting, updating, and unmounting phases during their lifecycle. Lifecycle hooks allow you to execute custom logic at specific stages of a component’s lifetime — such as fetching API data when a component mounts, adjusting DOM scroll positions after updates, capturing descendant errors, or cleaning up timers when unmounting.
Initialize non-reactive variables, prepare state values.
onMount()
Mounting
✅ Yes
Fetch initial API data, measure DOM dimensions, attach listeners, start timers.
onEnter()
Post-Mount Transition
✅ Yes
Trigger entrance animations or log page view telemetry immediately after initial render.
onBeforeUpdate()
Pre-Patch
✅ Yes
Read DOM scroll/cursor positions before patching updates.
onUpdate()
Post-Patch
✅ Yes
Adjust DOM scroll, re-initialize third-party DOM widgets.
onBeforeLeave()
Pre-Unmount Transition
✅ Yes
Postpone unmounting by returning a Promise (e.g. exit animations or confirm dialogs).
onLeave()
Unmount Transition
✅ Yes
Execute final transition cleanup immediately before internal teardown begins.
onUnmount()
Teardown
✅ Yes (pre-removal)
Clear timers (clearInterval), remove window listeners, close WebSockets.
onActivate(params)
Page Route Activation
✅ Yes
Runs on every page-route activation: after onMount() and optional onEnter() on the first activation, and when returning to a cached keepAlive page, with the latest route parameters.
onDeactivate()
KeepAlive Inactive
✅ Yes
Triggered when navigating away from a cached keepAlive page route.
onErrorCaptured()
Error Handling
✅ Yes
Catches unhandled errors thrown by descendant components.
Trigger: Runs right after reactive state and methods are initialized, immediately before the component’s HTML template is compiled and inserted into the DOM.
Use Cases: Initializing non-reactive local variables, computing pre-render data, or setting up early event listeners.
DOM Availability: The component’s DOM element (this.el) is not yet attached to the document.
onBeforeMount() {
console.log('Component is about to mount. Reactive state is ready.');
[!CAUTION]
Preventing Infinite Loops (AVX_R11): Do not mutate reactive state synchronously inside onBeforeUpdate() or onUpdate(). Mutating state inside these hooks triggers another update cycle, causing an infinite loop.
onDeactivate(): Runs when navigating away from an active keepAlive page instead of onUnmount(). The page instance then remains in the LRU cache.
onActivate(params): Runs on the first page-route activation after onMount() and optional onEnter(), and whenever the user returns to a cached keepAlive page. It receives the latest route parameters.
For a page configured with keepAlive: true and no onEnter() hook, the measured cumulative hook sequence is:
console.log(`Activated page for user ID: ${params.id}`);
awaitthis.refreshUserFeed(params.id);
}
onDeactivate() {
console.log('Page deactivated and saved to keepAlive cache.');
}
[!IMPORTANT]
Both onMount() and onActivate(params) run on the initial load. Putting the same fetch in both hooks fetches the data twice on a cold entry. Perform activation data fetching in onActivate() alone and reserve onMount() for one-time setup.
The runtime passes only params to onActivate(params); it does not provide a first-activation or cached-return flag. Hook arguments therefore cannot distinguish a cached return from every other later activation. If skipping the first activation is sufficient for the route flow, track activation on the component instance:
Trigger: Called when an unhandled exception is caught from a descendant child component.
Return Value: Return false to stop error propagation up the component tree and prevent application crashes.
Hooks run from the nearest component towards the page, then the application’s error handler. Returning nothing lets the error continue to the next ancestor. This applies to lifecycle errors and, when no declarative error fallback handles them, rendering errors and rejected resources. The instance argument identifies the child that failed.
onErrorCaptured(error, instance, info) {
console.error(`Captured error from ${instance.constructor.name} during ${info}:`, error);
this.state.hasError=true;
this.state.errorMessage=error.message;
returnfalse; // Suppress further error propagation up the tree
onEnter, onBeforeLeave, and onLeave work on both pages and components. In a single-file page or component, declare them with <action name="onEnter">, <action name="onBeforeLeave">, or <action name="onLeave">. Return the Promise from onBeforeLeave to keep the current content mounted until it resolves; returning nothing allows immediate teardown.
Trigger: Runs immediately after the component instance completes its initial mount and first render update (LifecycleManager.mount()).
Use Cases: Triggering entrance CSS transitions, Web Animations API sequences, tracking page view analytics/impressions, or setting initial focus.
DOM Availability: Fully mounted and accessible via this.el.
onEnter() {
console.log('Page/Component entered the active viewport.');
Trigger: Runs before component unmounting begins (LifecycleManager.unmount()).
Async Promise Return Mechanism: If onBeforeLeave() returns a Promise, LifecycleManagerpostpones unmounting and teardown until the returned Promise resolves (beforeLeaveResult.then(doTeardown)).
Use Cases:
Running asynchronous exit animations (e.g. fade-out, slide-up) so the component remains in the DOM until the animation completes.
Displaying custom unsaved changes confirmation dialogs before allowing the route transition and unmounting to proceed.
DOM Availability: Fully mounted and accessible during execution.
Avenx-JS supports async functions within lifecycle hooks. When an async lifecycle hook executes, state mutations made before an await statement trigger batched DOM updates via the microtask queue.
When making asynchronous requests in onMount(), the HTTP request may resolve after the user has navigated away and the component has unmounted. Updating state on an unmounted component can waste memory or lead to errors.
Use an AbortController to cancel pending requests on unmount: