@shopify/app-bridge-validate

App Bridge Validate is a middleware that validates action-instantiation props and payloads of dispatched actions. It can provide helpful error messages during development. As a separate package from app-bridge, this utility should be omitted in production to reduce file size.

Usage

To use the validator in an app, initialize your app with createAppWrapper instead of createApp. Using createAppWrapper allows you to pass in optional middlewares:

import {createAppWrapper, ClientApplication} from '@shopify/app-bridge';
import validatorMiddleware from '@shopify/app-bridge-validate';

const app = createAppWrapper(window.top, window.location.origin, [validatorMiddleware])({
  apiKey: 'API_KEY_FROM_PARTNER_DASH',
  shopOrigin: 'testshop.myshopify.io',
});

After the validator is set up, it validates action instantiation and dispatch against rules defined in the actions directory. Invalid actions will throw an error.

Validation in App Bridge Playground

The App Bridge Playground is set up to use the validator. To try it out, follow the setup steps from the playground package and then view the app with a shop.

Props validation

Edit code samples from any section of the playground app so that it creates an error. For example:

{
  message: "Unicorn",
  duration: '1234', // duration should be a positive integer
  isError: false,
}

Using the code above to instantiate a Toast action will throw an error. Details of the error can be found in the browser's debug console.

Dispatch validation

In the Any Action section of the playground, attempt to dispatch an action with an invalid payload. For example, try to dispatch the invalid Toast action below:

{
  "type": "APP::TOAST::SHOW",
  "group": "Toast",
  "payload": {
    "id": "123",
    "message": 1234 // message should be a string
  },
  "version": "1.0.0"
}

The action should result in an error with a message property that shows the path to where the error occurred:

{
  "error": {
    "action": {
      "type": "APP::TOAST::SHOW",
      "group": "Toast",
      "payload": {
        "id": "123",
        "message": 1234
      },
      "version": "1.0.0"
    },
    "message": "`type_error_expected_string` thrown for path: ['payload']['message'] and value: `1234` | `type_error_expected_integer` thrown for path: ['payload']['duration'] and value: `undefined`",
    "type": "APP::ERROR::INVALID_PAYLOAD",
    "id": "123"
  }
}

Creating validation rules

New actions and action groups in app-bridge should be accompanied by validation rules. Add new validation rules to a TS file with the name of the action.

The following example adds validation rules to toast.ts for the the Toast action:

import {MetaAction} from '@shopify/app-bridge/actions';
import {ActionType} from '@shopify/app-bridge/actions/Toast';
import {validate, ValidationError} from '@shopify/app-bridge-validate/type-validate';
import {createActionValidator} from '@shopify/app-bridge-validate/utils';

export const toastSchema = matchesObject({
  message: matchesString(),
  duration: matchesPositiveInteger(),
  isError: makeOptional(matchesBoolean()),
});

export function validateProps(props: Indexable) {
  return validate(props, toastSchema);
}

export function validateAction(action: MetaAction): ValidationError[] | undefined {
  switch (action.type) {
    case ActionType.SHOW:
      return validate(action, createActionValidator(ActionType, toastSchema, true));
    default:
      return validate(action, createActionValidator(ActionType));
  }
}