Chapter 1: Telegram Mini App Core Integration - Telemora/telemora-web GitHub Wiki

// src/core/init.ts
import {
  init as initSDK, // Alias to avoid name clash
  miniApp,
  mountBackButton,
  mountMiniAppSync,
  mountThemeParamsSync,
  setDebug,
  themeParams,
  viewport,
} from '@telegram-apps/sdk-react';

export function init(debug: boolean): void {
  // Check if we are running in a browser environment
  if (typeof window === 'undefined') return;

  // Enable SDK debugging if needed
  setDebug(debug);

  // Initialize the main SDK connection
  initSDK();

  // Mount and sync various SDK components
  mountBackButton();
  mountMiniAppSync();
  mountThemeParamsSync();

  // ... rest of the initialization for viewport and binding CSS variables
  // (See full code snippet below)
}

// src/core/init.ts (Continuing the init function)
import {
  init as initSDK,
  initData, // Used for user data, covered later
  miniApp,
  mountBackButton,
  mountMiniAppSync,
  mountThemeParamsSync,
  setDebug,
  themeParams,
  viewport,
} from '@telegram-apps/sdk-react';

export function init(debug: boolean): void {
  if (typeof window === 'undefined') return;
  setDebug(debug);

  initSDK();

  mountBackButton();
  mountMiniAppSync();
  mountThemeParamsSync();
  // initData.restore(); // This is for user data, covered in next chapter!

  // Mount and bind viewport properties
  void viewport
    .mount() // Start listening to viewport changes
    .then(() => {
      if (!viewport.isCssVarsBound()) {
        viewport.bindCssVars(); // Bind viewport CSS variables
      }
    })
    .catch((e) => {
      console.error('Something went wrong mounting the viewport', e);
    });

  // Bind Mini App and Theme properties to CSS variables
  if (!miniApp.isCssVarsBound()) {
    miniApp.bindCssVars();
  }

  if (!themeParams.isCssVarsBound()) {
    themeParams.bindCssVars();
  }

  // Optional: Initialize debugging tools in development
  if (debug) {
    import('eruda').then((lib) => lib.default.init()).catch(console.error);
  }
}

// src/libs/common/components/init-telegram.tsx
'use client'; // Important for Next.js client components

import { useLaunchParams } from '@telegram-apps/sdk-react'; // Hook to get Telegram params
import { type PropsWithChildren } from 'react';

import { init } from '@/core/init'; // Our init function
import { ErrorBoundary } from '@/libs/common/components/ErrorBoundary'; // Handles errors
import SplashScreen from '@/libs/common/components/splash-screen'; // Shows loading
import { useClientOnce } from '@/libs/common/hooks/useClientOnce'; // Runs code only once on client
import { useDidMount } from '@/libs/common/hooks/useDidMount'; // Checks if component is mounted

import { isDev } from '../utils'; // Helper to check development mode

export default function InitTelegram({ children }: PropsWithChildren) {
  // UseTelegramMock is for development/testing outside Telegram, skip for now
  // UseTelegramMock(isDev);

  const didMount = useDidMount(); // Check if the component has rendered

  // Get launch parameters from Telegram (like startParam)
  const launchParams = useLaunchParams();

  // Determine debug mode based on environment or launch param
  const debug = isDev || launchParams?.startParam === 'debug';

  // Call our init function only once on the client side
  useClientOnce(() => {
    init(debug);
  });

  // Show a splash screen while mounting/initializing
  if (!didMount) {
    return <SplashScreen />;
  }

  // Render children once mounted, wrapped in an error boundary
  return <ErrorBoundary fallback={TelegramErrorPage}>{children}</ErrorBoundary>;
}

// TelegramErrorPage is a simple fallback UI if initialization fails
function TelegramErrorPage({
  error,
  reset,
}: {
  error?: Error & { digest?: string };
  reset?: () => void;
}) {
  console.warn(error);
  return (
    <main>
      <pre>it seems you do not use telegram env</pre>
      {/* Button to reset error, hidden for simplicity */}
      {/* <button onClick={reset}></button> */}
    </main>
  );
}

// src/providers/AppProvider.tsx
'use client';

import dynamic from 'next/dynamic';
import { PropsWithChildren } from 'react';

// Import other providers used later in the tutorial
// import { QueryContext } from '@/libs/common/context/queryContext';
// import { UserProvider } from '@/libs/users/context/userContext';
// import TonConnectClientProvider from '@/providers/TonConnectClientProvider';

// Dynamically import InitTelegram, disabling Server-Side Rendering (SSR)
const InitTelegram = dynamic(() => import('@/libs/common/components/init-telegram'), {
  ssr: false, // This component only works in the browser
});

export function AppProvider({ children }: PropsWithChildren) {
  return (
    <>
      {/* InitTelegram is placed here so it runs early */}
      <InitTelegram>
        {/* Other providers for user data, payment, etc. wrap the rest of the app */}
        {/* <TonConnectClientProvider> */}
        {/*   <QueryContext> */}
        {/*     <UserProvider>{children}</UserProvider> */}
        {/*   </QueryContext> */}
        {/* </TonConnectClientProvider> */}
        {children} {/* The rest of your application */}
      </InitTelegram>
    </>
  );
}

// src/app/layout.tsx
import './globals.css'; // Global styles
import '@telegram-apps/telegram-ui/dist/styles.css'; // Styles for Telegram UI components

import type { Metadata } from 'next';
import type { PropsWithChildren } from 'react';

import { AppProvider } from '@/providers/AppProvider'; // Our AppProvider

export const metadata: Metadata = {
  title: 'Telemora',
  description: 'Telegram mini app',
  // ... other metadata
  manifest: '/manifest.json',
};

export default function RootLayout({ children }: PropsWithChildren) {
  return (
    <html lang="en" suppressHydrationWarning>
      {/* Body includes the AppProvider */}
      <body className="antialiased">
        <AppProvider>{children}</AppProvider> {/* AppProvider wraps everything */}
      </body>
    </html>
  );
}

// tailwind.config.ts
import { heroui } from '@heroui/theme';
import type { Config } from 'tailwindcss';

export default {
  content: [
    // ... file paths
  ],
  theme: {
    extend: {
      // ... other extensions
      colors: {
        // Mapping standard Tailwind colors to Telegram CSS variables
        background: 'var(--tg-theme-bg-color)',
        foreground: 'var(--tg-theme-text-color)',
        primary: 'var(--tg-theme-button-color)',
        'primary-text': 'var(--tg-theme-button-text-color)',
        secondary: 'var(--tg-theme-secondary-bg-color)',
        header: 'var(--tg-theme-header-bg-color)',
        accent: 'var(--tg-theme-accent-text-color)',
        link: 'var(--tg-theme-link-color)',
        hint: 'var(--tg-theme-hint-color)',
        subtitle: 'var(--tg-theme-subtitle-text-color)',
        destructive: 'var(--tg-theme-destructive-text-color)',
        section: {
          bg: 'var(--tg-theme-section-bg-color)',
          header: 'var(--tg-theme-section-header-text-color)',
          separator: 'var(--tg-theme-section-separator-color)',
        },
        bottomBar: 'var(--tg-theme-bottom-bar-bg-color)',
      },
      textColor: {
        DEFAULT: 'var(--tg-theme-text-color)',
        primary: 'var(--tg-theme-button-text-color)',
        // ... other text colors using CSS variables
      },
      backgroundColor: {
        DEFAULT: 'var(--tg-theme-bg-color)',
        primary: 'var(--tg-theme-button-color)',
        // ... other background colors using CSS variables
      },
      borderColor: {
        section: 'var(--tg-theme-section-separator-color)',
      },
      // ... rest of the config
    },
  },
  // ... rest of the config including heroui plugin which also uses these vars
} satisfies Config;