Telegram Mini Apps@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. The installation of the SDK itself is not required, as it is already included in @tma.js/sdk-solid.
pnpm i @tma.js/sdk-solidpnpm i @tma.js/sdk-solidnpm i @tma.js/sdk-solidnpm i @tma.js/sdk-solidyarn add @tma.js/sdk-solidyarn add @tma.js/sdk-solidUsage
SDKProvider
According to the @tma.js/sdk documentation, it consists of a set of components that are not initialized by default. Developers are responsible for creating these components themselves. However, the SDK provides the init function, which simplifies the process of creating the components and using the standard TWA flow. It handles all the necessary steps for developers.
To make the SDK functionality available to the application and allow the initialization of newly created components, we need to use the SDKProvider component.
import { SDKProvider } from '@tma.js/sdk-solid';
function Root() {
return (
<SDKProvider>
<div>My application!</div>
</SDKProvider>
);
}import { SDKProvider } from '@tma.js/sdk-solid';
function Root() {
return (
<SDKProvider>
<div>My application!</div>
</SDKProvider>
);
}Internally, the SDKProvider utilizes the init function from @tma.js/sdk. It accepts an optional list of parameters through the initOptions property, which is described here.
import { SDKProvider, SDKInitOptions } from '@tma.js/sdk-solid';
function Root() {
const options: SDKInitOptions = {
acceptScrollbarStyle: true,
checkCompat: true,
debug: true
};
return (
<SDKProvider initOptions={options}>
<div>My application!</div>
</SDKProvider>
);
}import { SDKProvider, SDKInitOptions } from '@tma.js/sdk-solid';
function Root() {
const options: SDKInitOptions = {
acceptScrollbarStyle: true,
checkCompat: true,
debug: true
};
return (
<SDKProvider initOptions={options}>
<div>My application!</div>
</SDKProvider>
);
}Most of the time, there is no need to use initOptions unless you have specific logic in your application. Typically, the SDK handles everything necessary for developers, so there is no need for additional configuration.
useSDKContext
By using the SDKProvider component, the child elements are able to utilize the useSDK hook to access core SDK information.
import { SDKProvider, useSDKContext } from '@tma.js/sdk-solid';
function App() {
const sdk = useSDKContext();
// Here we can use the SDK init information.
return <div>My application!</div>;
}
function Root() {
return (
<SDKProvider>
<App/>
</SDKProvider>
);
}import { SDKProvider, useSDKContext } from '@tma.js/sdk-solid';
function App() {
const sdk = useSDKContext();
// Here we can use the SDK init information.
return <div>My application!</div>;
}
function Root() {
return (
<SDKProvider>
<App/>
</SDKProvider>
);
}useSDK
Hook useSDK is used to gain access to provided SDK components.
WARNING
useSDK will throw an error in case, SDK is not yet ready to be used. To avoid this problem use useSDKContext to track the SDK init process.
import { createMemo, Switch, Match, ParentProps } from 'solid-js';
import { SDKProvider, useSDK, useSDKContext } from '@tma.js/sdk-solid';
function App() {
const sdk = useSDK();
// useSDK will not throw an error here as long as the App
// component will only be displayed in case, SDK is ready
// to be used.
return <div>My application!</div>;
}
/**
* Component responsible for controlling the process of application display.
*/
function DisplayGate(props: ParentProps) {
const { loading, error } = useSDKContext();
const errorMessage = createMemo < null | string > (() => {
const err = error();
if (!err) {
return null;
}
return err instanceof Error ? err.message : 'Unknown error';
});
return (
<Switch fallback={props.children}>
<Match when={errorMessage()}>
<p>
SDK was unable to initialize. Probably, current application is being used
not in Telegram Mini Apps environment.
</p>
<blockquote>
<p>{errorMessage()}</p>
</blockquote>
</Match>
<Match when={loading()}>
<div>Loading..</div>
</Match>
</Switch>
);
}
function Root() {
return (
<SDKProvider initOptions={{ debug: true }}>
<DisplayGate>
<App/>
</DisplayGate>
</SDKProvider>
);
}import { createMemo, Switch, Match, ParentProps } from 'solid-js';
import { SDKProvider, useSDK, useSDKContext } from '@tma.js/sdk-solid';
function App() {
const sdk = useSDK();
// useSDK will not throw an error here as long as the App
// component will only be displayed in case, SDK is ready
// to be used.
return <div>My application!</div>;
}
/**
* Component responsible for controlling the process of application display.
*/
function DisplayGate(props: ParentProps) {
const { loading, error } = useSDKContext();
const errorMessage = createMemo < null | string > (() => {
const err = error();
if (!err) {
return null;
}
return err instanceof Error ? err.message : 'Unknown error';
});
return (
<Switch fallback={props.children}>
<Match when={errorMessage()}>
<p>
SDK was unable to initialize. Probably, current application is being used
not in Telegram Mini Apps environment.
</p>
<blockquote>
<p>{errorMessage()}</p>
</blockquote>
</Match>
<Match when={loading()}>
<div>Loading..</div>
</Match>
</Switch>
);
}
function Root() {
return (
<SDKProvider initOptions={{ debug: true }}>
<DisplayGate>
<App/>
</DisplayGate>
</SDKProvider>
);
}