Wrappable Peregrine Talons

Usage

An extension may need to modify or decorate the behavior of a Peregrine talon. Third-party code may need to log to an external source when certain events occur, or may need to extend the model returned by the talon when a component calls it.

Wrapper modules

Talons are React hooks, and React hooks are plain functions. Therefore, you can use the function wrapper pattern to intercept talon functions.

The talon.wrapWith(module) method is simlar to the interceptor pattern also used in Magento backend plugins. Peregrine will dynamically inject the code from the passed module “around” the implementation of a talon, by passing the talon function through the wrapper function before exporting it.

Requirements

Wrapper modules for Peregrine talons must:

• be implemented in a separate file from the build-time Target code
• be accessible in frontend code via an import
• be a valid ES Module
• export one default function that implements the [TalonWrapper][] interface, i.e. it receives the original talon function as its parameter and must return a new talon function

Extensions which use wrapper modules must also intercept the Buildpack specialFeatures target and set the feature flag esModule: true.

Example

/* @my-extension/log-wrapper/intercept.js */

module.exports = targets => {
    const peregrineTargets = targets.of('@magento/peregrine');
    const talonsTarget = peregrineTargets.talons;

    talonsTarget.tap(talonWrapperConfig => {
        talonWrapperConfig.App.useApp.wrapWith('@my-extensions/log-wrapper');
    });
};

/* Module: @my-extensions/log-wrapper */

module.exports = function wrapUseApp(original) {
    return function useApp(...args) {
      console.log('calling useApp with', ...args);
      return original(...args);
    }

In the running PWA, the wrapUseApp function will run only once, on application load, at the time that useApp is first called. From that point on, this code will log arguments to the developer console every time useApp is called.

See the PWA Studio Target Experiments project repository for other documented examples of extensions that use PWA Studio’s extensibility framework.