SDK React

React bindings for client SDK. Contains hooks, components and other useful tools which allow usage of React along with Web Apps client SDK. Tracks SDK components changes out of box.

To learn how client SDK works, please, refer to its official documentation.

Installation

Before everything, it is assumed, that you already installed react package as long as this plugin has it as peer dependency. Installation of SDK itself is not required, current package already includes it.

Then, you can install this package via this command:

1npm i twa-client-sdk-react

or

1yarn add twa-client-sdk-react

Usage

Initializing

According to SDK documentation, it represents a set of components, which are not initialized by default and developer should create them by himself. Additionally, SDK provides function called init which allows developers not to think about "how do I even should create these components?" and creates components by itself.

So, as you could think, the first thing we have to do is to provide application SDK functionality and allow it calling initialization to get newly created components. For this purpose, component SDKProvider exist:

1import React from 'react';
2import {SDKProvider} from 'twa-client-sdk-react';
3
4function Root() {
5  return (
6    <SDKProvider>
7      <div>My application!</div>
8    </SDKProvider>
9  );
10}

Insertion of this component allows its child elements to use hook useSDK returning core SDK information:

1import React from 'react';
2import {SDKProvider, useSDK} from 'twa-client-sdk-react';
3
4function App() {
5  const sdk = useSDK();
6
7  // Here, we can use SDK information.
8
9  return <div>My application!</div>;
10}
11
12function Root() {
13  return (
14    <SDKProvider>
15      <App/>
16    </SDKProvider>
17  );
18}

Ok, we have access to SDK now, but what about init function? We don't have to call this function as long as SDKProvider will do it for us when it was attached to DOM. Let's complicate previous example and add important logic connected with SDK lifecycle:

1import React, {PropsWithChildren, useEffect} from 'react';
2import {SDKProvider, useSDK, useBackButton, useWebApp} from 'twa-client-sdk-react';
3
4/**
5 * Part of application which is free of using SDK components.
6 */
7function App() {
8  const backButton = useBackButton();
9  const webApp = useWebApp();
10
11  // When App is attached to DOM, lets show back button and
12  // add click event handler, which will close application.
13  useEffect(() => {
14    backButton.on('click', webApp.close);
15    backButton.show();
16
17    return () => {
18      backButton.off('click', webApp.close);
19      backButton.hide();
20    };
21    // We know, that backButton and webApp will never change,
22    // but let's follow React rules.
23  }, [backButton, webApp]);
24
25  return <div>My application!</div>;
26}
27
28/**
29 * This component controls render of important part of application
30 * which uses hooks, returning SDK components.
31 */
32function Loader({children}: PropsWithChildren) {
33  const {didInit, components} = useSDK();
34
35  // There were no calls of SDK's init function. It means, we did not
36  // even try to do it.
37  if (!didInit) {
38    return <div>SDK init function is not yet called.</div>;
39  }
40
41  // If components is null, it means, SDK is not ready at the
42  // moment and currently initializing. Usually, it takes like
43  // several milliseconds or something like that, but we should
44  // have this check.
45  if (components === null) {
46    return <div>Warming up SDK.</div>;
47  }
48
49  // Safely render application.
50  return <>{children}</>;
51}
52
53/**
54 * Root component of the whole project.
55 */
56export function Root() {
57  return (
58    <SDKProvider>
59      <Loader>
60        <App/>
61      </Loader>
62    </SDKProvider>
63  );
64}

You could probably ask why we should use component like Loader. The problem is, as long as SDK initialization is asynchronous (some of its components should send requests to native app), we could not determine which properties its components should have. That is the reason, why SDKProvider can not provide valid components property until initialization is completed.

As a result, all hooks which return component instances will throw an error as long as they could not get their component from components property. That is the reason, why these hooks should not be called until SDK is initialized.

When init is done

When initialization was completed successfully, do not forget to call webApp.ready function. This will notify native application about current Web App is ready to be displayed.

1import {useWebApp} from 'twa-client-sdk-react';
2import React, {useEffect} from 'react';
3
4function App() {
5  const webApp = useWebApp();
6
7  useEffect(() => {
8    webApp.ready();
9  }, [webApp]);
10  
11  return <div>Here is my App</div>;
12}

Hooks and HOCs

Theme

There are some cases, when it is required to use theme parameters information even when SDK is not ready yet. For example, you would probably want to know theme colors to render app loader with appropriate colors.

For this purpose, hook useThemeFromLocation is used:

1import {useThemeFromLocation} from 'twa-client-sdk-react';
2import React, {useEffect} from 'react';
3
4function App() {
5  const theme = useThemeFromLocation();
6
7  return <div>Background color: {theme.backgroundColor}</div>;
8}

Internally, this hook uses twa-theme-paramss package extractFromLocation function, which extracts theme information from current window location.

Other

Library provides list of dead simple hooks and HOCs for each SDK component. Returned instances are always the same, but force updates will be called in case, something changed in component.

WARNING: In case, you use HOCs, pay attention to the fact, passed components are always the same instances. This may lead to problems with PureComponents as long as they will not see any changes in references. Do not create new components instances as long as it will lead to new problems connected with events listening done during SDK initialization process.

Contribution

Any contribution is appreciated. Feel free to create new feature requests, bug reports etc.