Telegram Mini Apps Next.js Template

The Root component serves as the main application provider. Because Telegram Mini Apps have limitations with Server Side Rendering (SSR), the Root component uses a useDidMount hook to ensure the application only renders the full UI on the client side. During the initial server-side pass, it renders a loading state (<div className="root__loading">Loading</div>).

Once mounted, it wraps the application in several providers:

• TonConnectUIProvider: Configured with a manifest at /tonconnect-manifest.json for TON wallet connectivity.
• AppRoot (from @telegram-apps/telegram-ui): Configures the visual appearance (dark/light mode) and the platform-specific UI behavior based on Telegram's launch parameters.
• ErrorBoundary: Catches runtime errors and displays the ErrorPage component.

It also automatically synchronizes the application's locale with the user's Telegram language code using setLocale from the initData.user.language_code.

import { Root } from '@/components/Root/Root';

// Usage in layout.tsx or similar entry point
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <Root>
      {children}
    </Root>
  );
}

The init function is the primary entrypoint for setting up the application environment, configuring the @tma.js/sdk-react SDK, and mounting essential Telegram Mini App components. It handles debug mode, Eruda console integration, and provides a macOS-specific environment mock to bypass known client bugs.

Options

Side Effects

When called, init performs the following:

• SDK Setup: Calls setDebug and initSDK.
• Eruda: If enabled, initializes Eruda and positions it at the top-right corner.
• macOS Mocking: If mockForMacOS is enabled, it intercepts specific Telegram events to return correct theme parameters and safe area values.
• Component Mounting: Automatically mounts backButton, initData, miniApp, and viewport, and binds their respective CSS variables.

import { init } from './core/init';

await init({
  debug: true,
  eruda: true,
  mockForMacOS: false
});

The DisplayData component is a UI component used to render a list of data rows within a Section. It automatically formats different types of values into appropriate UI elements like links, checkboxes, or color indicators.

Row Types

Each object in the rows array must follow the DisplayDataRow type:

• Link type: { type: 'link', value?: string } — Renders an "Open" link using the provided URL.
• ReactNode type: { value: ReactNode } — Renders custom React elements. The component applies special logic based on the type of value:
  • string: If the string is a valid RGB color (detected via isRGB), it renders an <RGB /> component. Otherwise, it renders the string.
  • boolean: Renders a disabled <Checkbox /> indicating the state.
  • undefined: Renders an empty placeholder.

Props

• rows: An array of DisplayDataRow objects (required).
• header: Optional React node to display as the section header.
• footer: Optional React node to display as the section footer.

import { DisplayData, type DisplayDataRow } from '@/components/DisplayData/DisplayData';

const rows: DisplayDataRow[] = [
  { title: 'Status', value: true }, // Renders a disabled checkbox
  { title: 'Color', value: '#ff0000' }, // Renders an RGB color component
  { type: 'link', value: 'https://t.me/example' }, // Renders an "Open" link
  { title: 'Custom', value: <span>Custom Content</span> }, // Renders raw ReactNode
  { title: 'Empty', value: undefined }, // Renders *empty*
];

export const MyComponent = () => (
  <DisplayData 
    header={<span>My Data Section</span>} 
    rows={rows} 
  />
);