UNPKG

4.57 kBMarkdownView Raw
1# `@shopify/app-bridge`
2
3[![Build Status](https://travis-ci.com/Shopify/app-bridge.svg?token=RBRyvqQyN525bnfz7J8p&branch=master)](https://travis-ci.com/Shopify/app-bridge)
4[![codecov](https://codecov.io/gh/Shopify/app-bridge/branch/master/graph/badge.svg?token=nZ21m39Dr6)](https://codecov.io/gh/Shopify/app-bridge)
5[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
6[![npm version](https://badge.fury.io/js/%40shopify%2Fapp-bridge.svg)](https://badge.fury.io/js/%40shopify%2Fapp-bridge.svg)
7[![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@shopify/app-bridge.svg)](https://img.shields.io/bundlephobia/minzip/@shopify/app-bridge.svg)
8
9You can use Shopify App Bridge to embed apps and channels directly into the Shopify admin, Shopify Mobile, and Shopify POS. Shopify App Bridge helps to reduce your development time by accessing native Shopify features across different platforms, and makes sure that the user experience is consistent wherever merchants are using your app.
10
11Shopify App Bridge is currently being released as an update to all current consumers of the [Embedded App SDK](https://help.shopify.com/en/api/embedded-apps/embedded-app-sdk). Since it’s backwards compatible, you don't need to update your existing apps for them to support Shopify App Bridge.
12
13## Installation
14
15You can install Shopify App Bridge by using [Yarn](https://yarnpkg.com):
16
17``` sh
18yarn add @shopify/app-bridge
19```
20
21## Usage
22
23### Set up your app
24
25In the following example, you need to store `shopOrigin` during the authentication process and then retrieve it for the code to work properly. To learn more about this process, see [Getting and storing the shop origin](https://help.shopify.com/en/api/embedded-apps/shop-origin).
26
27Import the library from the `@shopify/app-bridge` package and provide a configuration:
28
29``` ts
30import createApp from '@shopify/app-bridge';
31
32const app = createApp({
33 apiKey: 'API key from Shopify Partner Dashboard',
34 shopOrigin: shopOrigin,
35});
36```
37
38### Actions
39
40Shopify App Bridge introduces the concept of actions. An action provides a way for applications and hosts to trigger events with a statically-typed payload.
41
42To learn more about the supported actions, see the [actions source folder](./src/actions).
43
44### App State
45
46Once the app is set up, you can access additional details and the state of the app at
47any time by making async call `app.getState()`:
48
49```ts
50app.getState().then((state: any) => {
51 console.info('App State: %o', state)
52});
53```
54
55You can also use a shorthand to retrieve nested properties by passing in a `query` when calling `getState(query)`, for example:
56
57```ts
58app.getState('pos.user').then((user: any) => {
59 console.log('POS User: %o', user);
60});
61```
62
63### Hooks
64
65Shopify App Bridge can be extended with hooks, which run when actions are dispatched and updated.
66Hooks are middleware that can modify or cancel actions.
67
68To learn more about hooks, see the [hooks source code](./src/client/Hooks.ts).
69
70### Development & Debugging
71
72Shopify App Bridge is shipped with a development build which includes the [validation middleware](./src/validate/README.MD) in order to provide helpful information during development.
73
74If you're consuming App Bridge from a CDN or using the UMD build, simply include the development version:
75`umd/index.development.js` instead of `umd/index.js`
76
77When consumed as JS Modules, development/production build is dynamically selected based on the `NODE_ENV` variable. Development build is used when `NODE_ENV=development`.
78
79Please note that the development build is not intended for production use, as the resulting file size is significantly larger due to the validator being present.
80
81## Contributing
82
83### Useful scripts
84
85- `yarn start` - Start a development server.
86- `yarn build` - Build the library, compiling the source TypeScript into JavaScript.
87- `yarn clean` - Remove any artifacts produced by the `build` script.
88- `yarn lint` - Run the source linter.
89- `yarn check` - Run the TypeScript type checker.
90
91### Running the tests
92
93- `yarn test` - Run the tests.
94- `yarn test:watch` - Run the tests in watch mode and auto-rerun on changes.
95- `yarn test:coverage` - Run the tests and generate a coverage report.
96
97### Prettier config
98
99To enable automatic prettier formatting, copy or link the pre-commit script to
100`.git/hooks/pre-commit` and make sure that it's executable.
101
102### Conventional Commits
103
104Please follow a standardized commit message format when contributing to this repo:
105https://www.conventionalcommits.org/en/v1.0.0-beta.2/