@storybook/appetize-utils NPM

Storybook Native

Storybook Native uses appetize.io to render your mobile application in an emulator that can be interacted with from your browser.

There are 2 ways to handle switching between stories:

1. Deep Linking

If your application is set to open up when the user requests a certain URL, you can use deep linking with storybook native. This approach is recommended over launch parameters, because you do not have to wait for the appetize.io session to reload when switching between stories.

In your application, you must add handlers that determines what to render based on what the query parameters for the deep link URL are.

Example URL:

sb-native://deep.link?component=button&theme=dark

If you wanted to use those query parameters, your application would need to parse the value associated with the component query parameter, and then render the corresponding component (in this case, a button component). Your application would also need to request either light or dark mode based on what the value of the theme query parameter is.

You do not need to exactly follow the above example for your query parameters! Your query parameters can have any information that you want.

Examples of parsing query parameters:

Android - parsing intents

You can read more about how to setup deep linking for Android here. Deep linking should also work on iOS and Flutter, but there are no examples for this yet.

2. Launch Parameters

appetize.io allows you to pass in custom launch parameters which will be sent to your mobile application when it first starts up. In your application, you must create a handler that determines what to render based on what those launch parameters are.

Example launch parameters:

{
  "component": "button",
  "theme": "dark"
}

If you wanted to use those launch parameters, your application would need to parse the value associated with the component key, and then render the corresponding component (in this case, a button component). Your application would also need to request either light or dark mode based on what the value of theme is.

You do not need to exactly follow the above example for your launch parameters! Your launch parameters object can have any information that you want.

Examples of parsing launch parameters:

More details about these parameters can be found in the bottom of the appetize.io docs

Usage

After you have modified your application to support launch parameters or query parameters, you must upload your application to appetize.io. After the upload, you will receive a public key that can be used with Storybook Native to view your application directly in storybook.

Storybook Native can then be used either as a build tool, or as a React component library that manages switching between stories.

You must create a .storybook folder with a main.js file inside of it, where you must configure the path to your stories, as well as any addons you want to use. The @storybook/addon-docs and @storybook/addon-controls addons must always be included. The @storybook/native-addon addon is required if you want to be able to rotate the emulator, capture screenshots, or switch between devices. Here is an example of a valid main.js file.

To enable switching between devices, you must also create a preview.js file in your .storybook folder, with the contents found here

If you are using deep linking, your .storybook folder MUST also have a preview-body.html that declares an iframe element with the id appetize-iframe. One example of this file can be found here. There is currently an issue where the appetize iframe still gets displayed when in the docs panel. A temporary workaround is to create a preview-head.html file in your .storybook folder with the following contents:

<style>
  #docs-root {
    position: absolute;
    z-index: 1;
    top: 0;
  }
</style>

Examples

Examples of how to use this module as both a build tool and as a component library can be found in this folder. The app folder inside each example contains the source code of the application the example is for.

Local development

Clone this repo
Run yarn to install dependencies
yarn build && cd examples/android-material-ui && yarn start
Anytime changes are made, yarn build and start must be re-run