Hooks

Overview

Hybridly's requests have their own lifecycle. It's sometimes necessary to hook into some of its events to perform custom logic.

For instance, the progress bar is implemented using these hooks.

There are a two main ways to catch Hybridly's events: globally, through plugins, or locally, through visit options.

Plugins

Plugins can be registered through initializeHybridly's plugins option. They have access to all request lifecycle events, plus a few additionnal plugin-specific hooks.

They are useful when you need to execute custom logic for each request. You can learn more about plugins in their documentation.

Registering hooks manually

Though it's highly recommended to use plugins, it's also possible to register hooks with the registerHook function.

This may be useful for requirements for which plugins could be overkill.

<script setup lang="ts">
registerHook('navigated', ({ type }) => {
  if (type === 'back-forward') {
    router.reload()
  }
})
</script>

Visit options

When navigating or using the form util, it's possible to pass a hook object that accepts a callback for each lifecycle event.

These callbacks will be executed just once for the current request. You can learn more about visit options in their documentation.

Request lifecycle events

The following lifecycle events can be hooked into when making a request, via the hooks navigation option. They may be awaited if necessary.

export interface RequestHooks {
	/**
	 * Called before a navigation request is going to happen.
	 */
	before: (options: HybridRequestOptions, context: InternalRouterContext) => MaybePromise<any | boolean>

	/**
	 * Called before the request of a navigation is going to happen.
	 */
	start: (context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when progress on the request is being made.
	 */
	progress: (progress: Progress, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when data is received after a request for a navigation.
	 */
	data: (response: AxiosResponse, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when a request is successful and there is no error.
	 */
	success: (payload: HybridPayload, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when a request is successful but there were errors.
	 */
	error: (errors: Errors, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when a request has been aborted.
	 */
	abort: (context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when a response to a request is not a valid hybrid response.
	 */
	invalid: (response: AxiosResponse, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called when an unknowne exception was triggered.
	 */
	exception: (error: Error, context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called whenever the request failed, for any reason, in addition to other hooks.
	 */
	fail: (context: InternalRouterContext) => MaybePromise<any>

	/**
	 * Called after a request has been made, even if it didn't succeed.
	 */
	after: (context: InternalRouterContext) => MaybePromise<any>
}