@tma.js/sdk-solid

Solid bindings for @tma.js/sdk. The package connects reactive values of SDK components to Solid's reactivity.

TIP

The package extends @tma.js/sdk, so it is recommended to review the SDK documentation first.

Upgrading from 3.x?

See Migrating from 3.x.

Installation

The package requires @tma.js/sdk and solid-js 1.x as peer dependencies.

pnpm

pnpm i @tma.js/sdk @tma.js/sdk-solid

npm

npm i @tma.js/sdk @tma.js/sdk-solid

yarn

yarn add @tma.js/sdk @tma.js/sdk-solid

INFO

The package re-exports everything from @tma.js/sdk, so you can import both the SDK and useComputed from @tma.js/sdk-solid. The SDK is a peer dependency, so the application always has a single copy of it: its components are singletons with their own state.

Usage

Initialize the SDK and mount the components you use before rendering the application. Then read the components state using useComputed.

index.tsx

import { render } from 'solid-js/web';
import { init, backButton } from '@tma.js/sdk-solid';

import { BackButton } from './BackButton.js';

// Initialize the SDK.
init();

// Mount the Back Button, so it works with its actual state.
backButton.mount();

render(() => <BackButton/>, document.getElementById('root')!);

BackButton.tsx

import { createEffect, onCleanup, onMount } from 'solid-js';
import { backButton, useComputed } from '@tma.js/sdk-solid';

/**
 * Component controlling the Back Button visibility.
 */
export function BackButton() {
  const isVisible = useComputed(backButton.isVisible);

  createEffect(() => {
    console.log('The button is', isVisible() ? 'visible' : 'hidden');
  });

  onMount(() => {
    backButton.show();
    onCleanup(() => {
      backButton.hide();
    });
  });

  return null;
}

useComputed

Reactive values of SDK components, like backButton.isVisible or mainButton.state, are computed values (the Computed type). Calling such a value returns its current state, and its subscribe method tracks changes.

useComputed returns a Solid accessor updated whenever the computed value changes.

import { backButton, mainButton, useComputed } from '@tma.js/sdk-solid';

function Status() {
  const isVisible = useComputed(backButton.isVisible);
  const mainButtonState = useComputed(mainButton.state);

  return (
    <>
      <p>Back button is {isVisible() ? 'visible' : 'hidden'}</p>
      <p>Main button text: {mainButtonState().text}</p>
    </>
  );
}

The hook accepts only computed values provided by the SDK. To store your own reactive state, use Solid's createSignal or createStore.

Values are stored as is, so a computed value holding a function returns this function from the accessor.

Lifetime

Inside a reactive owner, e.g. a component or createRoot, the subscription is removed when the owner is disposed.

useComputed can also be called outside any owner, e.g. in a module scope, to create an accessor shared by the whole application. In this case, the subscription is never removed, so avoid calling it this way repeatedly.

import { mainButton, useComputed } from '@tma.js/sdk-solid';

// Created once and used across the application.
export const isMainButtonVisible = useComputed(mainButton.isVisible);