Skip to main content
These are the callback contracts used by native app extensions. The type definitions below describe the values passed to each extension function and the mutations it may return. Function names in these declarations are the template defaults. Your entry file must export each function under the functionName of its entry in napps.config.json; see How App Extensions work. Async callbacks share the host’s extension timeout. Keep work bounded and return within the documented three-second budget. A timed-out or rejected promise is treated as a failed callback and native behavior continues according to the extension contract.

Product listing formatter

The editor is mutable for the duration of the callback. Make formatting idempotent because the same listing can be formatted more than once.

Collection filters

trigger is either "Initial" or "UserFiltersChanged". The callback can change the editor before the product query runs. Boolean mutators return false when the requested filter or value does not exist.

Product detail handler

The module exports a factory that returns the handler. The factory receives this context and these arguments:
Callbacks that support cancellation suppress the delegated native callback when they return false. There is no preventDefault() method on the event object. onAddedToCart receives { product, productVariant, quantity }; its quantity is the increase observed after the native cart addition, so returning false does not undo that addition. onProductSelected receives { product, productVariant }. onBeforeProductAddToCart receives { product, variant, quantity }.

PDP formatting and media tags

Media is native-owned: handlers can inspect the gallery and manage tags, but cannot reorder or add media. A tag with the same ID on one media item is replaced. A tag must provide text, an icon, or both.

Cart operations

Use the returned operations from the cart extension. Operations are applied by the native runner; do not mutate a CartOperation after returning it. CartOperations is a runtime global typed CartOperations | undefined, also available as NAPPS.CartOperations. The package exports the interface as a type only.

Cart line-item formatter

The formatter may change presentation and checkout availability. The line item’s product and variant references can be null when the underlying catalog object no longer exists.

Product-card bridge

Product-card modules receive their products through ComponentContext.cards.
The bridge invokes the subscriber immediately and keeps only the latest subscriber. Render one root child per slot, with real products first and loading placeholders last.