@tma.js/sdk-solid

Solid JS bindings for client SDK. Includes hooks, components and utilities for comfortable usage of Solid JS on the Telegram Mini Apps platform.

Installation

Before anything else, it is assumed that you have already installed the solid-js package, as it is a peer dependency of this package.

pnpm

pnpm i @tma.js/sdk-solid

npm

npm i @tma.js/sdk-solid

yarn

yarn add @tma.js/sdk-solid

SDKProvider

SDKProvider is a component responsible for providing the SDK functionality. It accepts such properties as acceptCustomStyles: boolean and debug: boolean. Both of them are optional.

The acceptCustomStyles property is responsible for accepting custom styles from the web version of Telegram.

The debug property is responsible for enabling a debug mode.

import { SDKProvider } from '@tma.js/sdk-solid';

/**
 * Root component for the whole project.
 */
export function Root() {
  return (
    <SDKProvider acceptCustomStyles debug>
      <div>My application!</div>
    </SDKProvider>
  );
}

Hooks

Each component hook in this package returns a custom signal. The returned signal contains a property error?: unknown, which will be set if something goes wrong during component initialization. Calling a signal containing this property will lead to throwing a corresponding error. If no error occurs, the signal will return a component instance.

For better understanding, each component hook uses its own component-related init function. If the init function returns a non-promise value, the hook will instantly retrieve it. If the init function is asynchronous, the hook will return a signal with an undefined value while the component is still initializing. Then, it will be updated to the initialized value.

Here is an example:

import { useBackButton, useViewport } from '@tma.js/sdk-solid';

// BackButton initializes synchronously. So, bb will be a signal
// returning an instance of BackButton.
const bb = useBackButton();
const bbV = bb(); // will be BackButton

// Viewport is being initialized asynchronously, so signal may return undefined.
// After some time it will receive a valid value.
const vp = useViewport();
const vpV = vp(); // will be undefined

// ...after some time
const vpV2 = vp(); // will be Viewport

It is important to note that all properties of the components are reactive. So, if something changes in a value returned from the hook signal, the signal itself will not be notified. This is because the component itself did not change, but its property did.

Let's take a look at this example:

import { useViewport } from '@tma.js/sdk-solid';
import { createEffect } from 'solid-js';

// Let's assume that viewport is already initialized.
const vp = useViewport();

createEffect(() => {
  // This line of code will not be called if the viewport height 
  // or expansion state changes.
  console.log('Viewport changed', vp());
});

createEffect(() => {
  // But this line of code will be called every time the viewport
  // height changes.
  console.log('Viewport height changed', vp().height);
});

We have this granular reactivity to provide maximal performance, like Solid itself does.

HOCs

All package Higher Order Components utilize the hooks described previously. The usage is rather simple:

import { withBackButton } from '@tma.js/sdk-solid';

const MyComponent = withBackButton('bb', (props) => {
  createEffect(() => {
    props.bb().show();
  });
  return null;
});

As the first argument, you must pass a value responsible for the component property name receiving a hook result. Note that the received value will be a signal, not the value behind it.

Hooks and HOCs List

Hook	HOC	Signal value
useBackButton	withBackButton	BackButton
useBiometryManager	withBiometryManager	BiometryManager or undefined
useClosingBehavior	withClosingBehavior	ClosingBehavior
useCloudStorage	withCloudStorage	CloudStorage
useHapticFeedback	withHapticFeedback	HapticFeedback
useInitData	withInitData	InitData
useInvoice	withInvoice	Invoice
useMainButton	withMainButton	MainButton
useMiniApp	withMiniApp	MiniApp
usePopup	withPopup	Popup
useQRScanner	withQRScanner	QRScanner
useSettingsButton	withSettingsButton	SettingsButton
useThemeParams	withThemeParams	ThemeParams
useUtils	withUtils	Utils
useViewport	withViewport	Viewport or undefined

Template

We have already created a template for Solid JS that utilizes the current package, so you can use it.