@crystallize/app-signal

Provides a way for your app or frontend to talk to the Crystallize app.

Changelog

Apps 📱

Signal that the app is ready

import { signal } from '@crystallize/app-signal';

document.addEventListener("DOMContentLoaded", () => signal.send('ready'));

Links to the Crystallize App

For creating links to the Crystallize app, you should follow this practice:

import { signal } from '@crystallize/app-signal';

const linkToParams = { area: 'item', id: '123' }

<a href={signal.getUrl(linkToParams)} target={linkToParams.target} onClick={(event) => {
  // Stop if the user wants to open in a new tab
  if (!(2 === event.which || event.metaKey || event.ctrlKey)) {
    event.preventDefault();
    signal.navigateTo(linkToParams);
  }
})>Go to {linkToParams.area} in the Crystallize app</a>

Here are all the things you can navigate to

import { signal } from '@crystallize/app-signal';


// Navigate to an item using id
await signal.navigateTo({
  area: 'item',
  id: '<itemId>'
});

// Navigate to an item using external reference
await signal.navigateTo({
  area: 'item',
  externalReference: '<refId>'
});

// Navigate to a product variant using SKU
await signal.navigateTo({
  area: 'productVariant',
  sku: '<sku>'
});

// Navigate to a customer
await signal.navigateTo({
  area: 'customer',
  identifier: '<identifier>'
});

// Navigate to an order
await signal.navigateTo({
  area: 'order',
  id: '<orderId>'
});

// Navigate to a grid
await signal.navigateTo({
  area: 'grid',
  id: '<id>'
});

// Navigate to a topic
await signal.navigateTo({
  area: 'topic',
  id: '<id>'
});

// Navigate to a fulfilment pipeline
await signal.navigateTo({
  area: 'fulfilmentPipeline',
  id: '<id>'
});

// Navigate to an app
await signal.navigateTo({
  area: 'app',
  id: '<identifier>'
});

Navigate the main catalogue item in a split view (keeps the split open)

Unlike navigateTo({ area: 'item', ... }) — which routes through /take-me-to and closes any open split view — navigateToCatalogueItem changes the main (alpha) catalogue item in place, preserving an open split view. You must supply the item type (the catalogue route segment) so no extra lookup is needed.

import { signal } from '@crystallize/app-signal';

await signal.navigateToCatalogueItem({
  id: '<itemId>',
  type: 'product', // 'folder' | 'product' | 'document'
  sku: '<sku>',    // optional — target a specific product variant
});

Use getCatalogueItemUrl (the counterpart of getUrl) to build the same link for an <a href>:

import { signal } from '@crystallize/app-signal';

const to = { id: '<itemId>', type: 'product' };

<a href={signal.getCatalogueItemUrl(to)} onClick={(event) => {
  // Stop if the user wants to open in a new tab
  if (!(2 === event.which || event.metaKey || event.ctrlKey)) {
    event.preventDefault();
    signal.navigateToCatalogueItem(to);
  }
})>Go to item, keeping the split view open</a>

Other signals

import { signal } from '@crystallize/app-signal';

// The menu listing all apps
await signal.toggleAreaMenu(true);

// Change app language
await signal.changeLanguage('pt');

Scroll to a component in the item editor

Ask the Crystallize app to scroll the item editor to a specific component:

import { signal } from '@crystallize/app-signal';

await signal.scrollToComponent('specs/0/title');

The argument is a component path (pathId) identifying the target component in the open item. If no component matches the path (unknown, hidden, or a different item is open), the app does nothing — the call is a safe no-op.

Constructing the component path (pathId)

The path is built from /-joined segments, descending from a top-level component on the item's shape. Use the component's identifier (from the shape), and for repeatable containers, the zero-based index of the entry.

| Target | Path pattern | Example | | --- | --- | --- | | A top-level component | <componentId> | description | | A chunk entry (row) | <chunkId>/<index> | specs/0 | | A component inside a chunk entry | <chunkId>/<index>/<innerComponentId> | specs/0/title | | The selected component of a choice | <choiceId>/<selectedComponentId> | cta/link | | A multiple-choice entry's selected component | <multipleChoiceId>/<index>/<selectedComponentId> | tags/2/url |

Variants expose four fixed built-in sections, addressed by literal ids:

| Section | Path | | --- | --- | | Media | _variant-media | | Attributes | _variant-attributes | | Stock | _variant-stock | | Prices | _variant-prices |

Frontend previews 🖥

Frontend previews are a way of embedding your websites within Crystallize, allowing you to preview how content will look like for the end user. Learn more at Frontend previews.

No config setup

This will work with the majority of frontends, and will trigger page reload using location.reload() when the app wants it to.

<script src="https://unpkg.com/@crystallize/app-signal/dist/frontend-preview-listener.js"></script>

Advanced setup

This is to be used if you want more control over how the frontend is embedded within Crystallize. You should implement two distinct handlers:

1. Notify that the frontend preview is ready

import { signal } from '@crystallize/app-signal';

document.addEventListener("DOMContentLoaded", () => signal.send('ready'));

2. Reload the page when the app wants to. This will be when the reload button is pressed, or when content is changed and "live mode" is activated.

import { signal } from '@crystallize/app-signal';

signal.on('reload', function () {
  location.reload();
  signal.send('reloading');
})

Catching errors

Every signal sent to the app is async, and should be wrapped in a try...catch clause, like so:

import { signal } from '@crystallize/app-signal';

try {
  await signal.send('some.bogus.message');
} catch(error) {
  console.error('Could not send the message');
  console.log(error);
}

SSR

In order to generate the correct links and such on the server side, you need to pass the context.

import { signal } from '@crystallize/app-signal';

signal.setContext({
  origin: 'https://app.crystallize.com',
  tenantId: '<your-tenant-id>',
  tenantIdentifier: '<your-tenant-identifier>',
  language: 'en'
})