@shopify/app-bridge-host/README.md

# `@shopify/app-bridge-host`

App Bridge Host contains components and middleware to be consumed by the app's host, as well as the host itself. The middleware and `Frame` component are responsible for facilitating communication between the client and host, and used to act on actions sent from the [App Bridge client](../app-bridge/). This package is used by Shopify's web admin.

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)

## App Bridge Host architecture

The App Bridge host uses a cross-platform, modular architecture. The host has several responsibilities. First, the host brokers communication between contexts (ie between the app and Shopify Admin). Second, the host maintains a central store representing the current state of all App Bridge features, which is exposed to the client app. Third, the host provides functionality to the client app.

Functionality is exposed to the client app via App Bridge actions. When an action is dispatched using App Bridge, the host evaluates the action against the relevant reducers, which make changes to the central store of app state. The state is then passed to UI components, which render functionality based on the state.

Features and UI components are treated separately in App Bridge. A feature consists of an action set and reducers, and the associated UI component consumes the resulting state. Most UI components have an associated feature, but this is not required.

The `<HostProvider>` is not responsible for rendering the client app, by Iframe or other means.

## Building an App Bridge host

You can create your own App Bridge host using the `<HostProvider>` component.

`<HostProvider>` requires three types of data: app configuration, functionality to provide to the client app, and an initial state for the store.

### App configuration

The `<HostProvider>` requires configuration information about the client app to be loaded:

```js
const config = {
  apiKey: 'API key from Shopify Partner Dashboard',
  appId: 'app id from GraphQL',
  handle: 'my-app-handle',
  shopId: 'shop id from GraphQL',
  url: 'app url from Shopify Partner Dashboard',
  name: 'app name',
};
```

Note that we'll be referring to this sample config throughout the examples below.

#### Providing functionality

The `<HostProvider>` does not load any components by default. In order to provide a feature to an app, you must load the necessary component(s).

You can find pre-defined host UI components inside the `@shopify/app-bridge-host/components` directory. You can also write your own components.

#### Initial state

In App Bridge, features are gated using a permission model, which lives in the store. All feature permissions default to `false`. To provide a feature, you must also set the relevant permissions. If you don’t, the client app will not be permitted to use the feature, even if the component is available. Most components are associated with a single feature, but this is not a requirement.

The `<HostProvider>` accepts an initial state for the store. This allows a host to pre-populate the store with information the app can immediately access, such as feature permissions.

The `setFeaturesAvailable` utility can be used to build the `initialState.features` object. The following example shows a host with several components, and the corresponding feature availability set in `initialState`:

```tsx
import {HostProvider} from '@shopify/app-bridge-host';
import {Loading} from '@shopify/app-bridge-host/components/Loading';
import {Modal} from '@shopify/app-bridge-host/components/Modal';
import {Navigation} from '@shopify/app-bridge-host/components/Navigation';

import {Group} from '@shopify/app-bridge/actions';
import {setFeaturesAvailable} from '@shopify/app-bridge-host/store';

const initialState = {
  features: setFeaturesAvailable(Group.Loading, Group.Modal, Group.Navigation),
};

function Host() {
  return (
    <HostProvider
      config={config}
      components={[Loading, Modal, Navigation]}
      initialState={initialState}
    />
  );
}
```

### Custom components

`HostProvider` can render any type of React component; it’s not limited to the components in this package. You can use either the `withFeature` decorator or the `useFeature` hook to connect a custom component to an App Bridge feature.

Your custom components can also be functional components that don't render UI, you just need to ensure it returns `null`:

```tsx
function nonUI() {
  // do something non UI
  return null;
}
```

#### withFeature

To connect a component to the App Bridge host, wrap it using the `withFeature` decorator. This decorator provides the component with access to the `store` and `actions` for a specified App Bridge feature (remember to set the corresponding feature permissions in `initialState`).

This decorator only renders your custom component when the `store` for the specified feature is not `undefined`. This means you do not have to do an `undefined` check before accessing the store.

Here is an example of creating a custom component that utilizes the App Bridge `Toast` feature, rendering the `Toast` component from Polaris.

```tsx
import {HostProvider, ComponentProps, withFeature} from '@shopify/app-bridge-host';
import {
  feature as toastFeature,
  WithFeature,
} from '@shopify/app-bridge-host/store/reducers/embeddedApp/toast';
import {Toast} from '@shopify/polaris';
import compose from '@shopify/react-compose';

function CustomToastComponent(props: WithFeature) {
  const {
    actions,
    store: {content},
  } = props;

  if (!content) {
    return null;
  }

  const {duration, error, id, message} = content;
  return (
    <Toast
      error={error}
      duration={duration}
      onDismiss={() => actions.clear({id: id})}
      content={message}
    />
  );
}

const Toast = compose<ComponentProps>(withFeature(toastFeature))(CustomToastComponent);

const initialState = {
  features: setFeaturesAvailable(Group.Toast),
};

function Host() {
  return <HostProvider config={config} initialState={initialState} components={[Toast]} />;
}
```

#### useFeature

Use the `useFeature` hook to connect your component to the App Bridge host. This hook returns an array with the `store` and `actions` for a specified App Bridge feature (remember to set the corresponding feature permissions in `initialState`).

The hook is useful when you want to use one component to handle multiple related features. For example, a single component can be used to render the Menu and Title Bar features.

One thing to note is that you need to do an `undefined` check before accessing the `store` to prevent errors.

Here is an example of creating a custom component that utilizes the App Bridge `TitleBar` and `Menu` feature and uses the [`useRouterContext` hook](src/hooks/README.md#useRouterContext) to access the router:

```tsx
import {HostProvider, useRouterContext, useFeature} from '@shopify/app-bridge-host';
import {feature as titleBarFeature} from '@shopify/app-bridge-host/store/reducers/embeddedApp/titleBar';
import {feature as menuFeature} from '@shopify/app-bridge-host/store/reducers/embeddedApp/menu';
import {Toast} from '@shopify/polaris';

function TitleBarWithMenu() {
  const {appRoot} = useRouterContext();
  const [titleBarStore, titleBarActions] = useFeature(titleBarFeature);
  const [menuStore, menuActions] = useFeature(menuFeature);

  const items = menuStore?.navigationMenu?.items || [];

  return (
    <div>
      <div>{titleBarStore?.title}</div>
      <ul>
        {items.map(({label, destination: {path}}) => {
          const appUrl = `/admin/apps/${appRoot}`;
          const href = `${appUrl}/${path}`;
          return (
            <li>
              <a href={href}>{label}</a>
            </li>
          );
        })}
      </ul>
    </div>
  );
}

const initialState = {
  features: setFeaturesAvailable(Group.TitleBar, Group.Menu),
};

function Host() {
  return (
    <HostProvider config={config} initialState={initialState} components={[TitleBarWithMenu]} />
  );
}
```

#### useFeature

### Asynchronous components

You can load host components asynchronously, ie using [@shopify/react-async](https://github.com/Shopify/quilt/tree/master/packages/react-async). The `<HostProvider>` handles adding the feature's reducer to the Redux store. Actions that are dispatched by the app before the feature is available is automatically queued and resolved once the feature's component is loaded.

```tsx
import {createAsyncComponent, DeferTiming} from '@shopify/react-async';
import {HostProvider} from '@shopify/app-bridge-host';

const Loading = createAsyncComponent<ComponentProps>({
  load: () =>
    import(
      /* webpackChunkName: 'AppBridgeLoading' */ '@shopify/app-bridge-host/components/Loading'
    ),
  defer: DeferTiming.Idle,
  displayName: 'AppBridgeLoading',
});

function Host() {
  return <HostProvider config={config} components={[Loading]} router={router} />;
}
```

### Rendering the client app, with navigation

Since `<HostProvider>` is not responsible for rendering the client app, one of the `components` must handle this task. The Apps section in Shopify Admin uses the `MainFrame` component, which additionally requires a router context to provide navigation to the client app.

If you want to provide navigation capabilities to your app, you will need to include the `Navigation` component and provide a router to the `<HostProvider>`. The router should keep the app’s current location in sync with the host page’s current location, and manage updating the location when the route changes.

The following example shows a simple router being passed into `<HostProvider>`, along with the `MainFrame` and `Navigation` components:

```ts
import {HostProvider} from '@shopify/app-bridge-host';
import {MainFrame} from '@shopify/app-bridge-host/components/MainFrame';
import {Navigation} from '@shopify/app-bridge-host/components/Navigation';

const router = {
  location: {
    pathname: window.location.pathname,
    search: window.location.search,
  },
  history: {
    push(path: string) {
      window.history.pushState('', null, path);
    },
    replace(path: string) {
      window.history.replaceState('', null, path);
    },
  },
};

const initialState = {
  features: setFeaturesAvailable(Group.Navigation),
};

function Host() {
  return (
    <HostProvider
      config={config}
      components={[MainFrame, Navigation]}
      initialState={initialState}
      router={router}
    />
  );
}
```

Note that since `MainFrame` only renders the app itself and does not provide features to the app, there is no related `initialState`. `Navigation`, however, provides a feature to the app. To allow the app to use that feature, it is made made available in `initialState`.

### Communicating with the loaded app

Certain App Bridge feature requires subscribing to actions dispatched by the app. For example, the Auth Code or Session Token features both respond to a request action from the app.

You can communicate with the client app by using the [`useHostContext` hook](src/hooks/README.md#useHostContext).

The following example shows a Session Token component communicating with the client app:

```tsx
import {HostProvider, useHostContext, useFeature} from '@shopify/app-bridge-host';
import {SessionToken} from '@shopify/app-bridge/actions';
import {feature} from '@shopify/app-bridge-host/features/sessionToken';

function SessionTokenComponent() {
  const {app} = useHostContext();
  const [store, actions] = useFeature(feature);

  useEffect(() => {
    return app.subscribe(SessionToken.ActionType.REQUEST, () =>
      actions.respond({sessionToken: 'TEST-SESSION-TOKEN'}),
    );
  }, [actions, hostContext]);

  return null;
}

const initialState = {
  features: setFeaturesAvailable(Group.SessionToken),
};

function Host() {
  return (
    <HostProvider
      config={config}
      components={[SessionTokenComponent]}
      initialState={initialState}
    />
  );
}
```