Telegram Mini App Boilerplate

Get started building mini apps for Telegram with our straightforward Telegram Mini App Boilerplate. Simple, efficient, and well-documented – it's your perfect starting point for crafting engaging experiences. Dive in and create something awesome!

Tech Stack

I'm using Next.js with app router along with shadcn/ui, Tailwind CSS, and tma.js (a Telegram miniapp wrapper that provides telegram auth user). It will be fun, let's go.

Steps (Mini App)

In case you are customizing your own, you may follow the steps:

Install @tma.js/sdk and @tma.js/sdk-react packages:

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

Create a Telegram mini app provider initial state component:

// src/components/tma/tma-provider-initial-state.tsx

import { Logo } from "@/components/logo";

export function TmaProviderInitialState() {
  return (
    <div>
      <Logo className="w-12 h-12 text-primary-foreground" />
    </div>
  );
}

Create a Telegram mini app loading component:

// src/components/tma/tma-provider-loading.tsx

import { Loader } from "@/components/loader";

export function TmaProviderLoading() {
  return (
    <div className="flex text-muted-foreground gap-2 text-sm items-center">
      <Loader />
    </div>
  );
}

Also, create a Telegram mini app error component:

// src/components/tma/tma-provider-error.tsx

type TmaProviderErrorProps = {
  error: unknown;
};

export function TmaProviderError({ error }: TmaProviderErrorProps) {
  const errorMessage =
    error instanceof Error ? error.message : JSON.stringify(error);

  return (
    <div className="h-screen grid place-items-center">
      <span>
        <strong>Oops. Something went wrong.</strong>
        <blockquote>
          <code>{errorMessage}</code>
        </blockquote>
      </span>
    </div>
  );
}

Now, let's create a Telegram mini app provider and make sure it's a client component. You can customize options as per your needs (docs). Also, add those custom components we just created in the component:

// src/components/tma/index.tsx

"use client";

import { PropsWithChildren } from "react";
import { DisplayGate, SDKProvider } from "@tma.js/sdk-react";
import { TmaProviderError } from "./tma-provider-error";
import { TmaProviderLoading } from "./tma-provider-loading";
import { TmaProviderInitialState } from "./tma-provider-initial-state";

export function TmaSDKProvider({ children }: PropsWithChildren) {
  return (
    <SDKProvider
      options={{ cssVars: true, acceptCustomStyles: true, async: true }}
    >
      <DisplayGate
        error={TmaProviderError}
        loading={TmaProviderLoading}
        initial={TmaProviderInitialState}
      >
        {children}
      </DisplayGate>
    </SDKProvider>
  );
}

Finally, add Tma SDK provider to the root layout:

// src/app/layout.tsx

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import { TmaSDKProvider } from "@/components/tma";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "My Telegram Mini App",
  description: "A mini app for Telegram.",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        {/*This will Provide Telegram authenticated user */}
        <TmaSDKProvider>{children}</TmaSDKProvider>
      </body>
    </html>
  );
}

Start your app

pnpm dev

Now make your app publicly accessible:

You can use ngrok

ngrok http 3000

Next lets setup telegram bot.

Telegram Bot

Now let's set up our Telegram bot. For Telegram bot I'll use Nodejs with Typescript, Dotenv and Telegraph, if you are following this repo cd to bot or setup a separate project and install depencies:

pnpm i dotenv telegraf

Steps (Bot)

First, obtain your Telegram bot tokens.

I'll use BotFather to create a bot in this demo.

Open Telegram on your device, search for BotFather in the search bar.
Then send the `/newbot`` command to Telegram.
Choose a suitable name and username, then copy the token.

Go to bot/src and create a .env file.
Fill in your bot token and ngrok public URL:

# bot/src/.env

NODE_ENV="development"

# Telegram Bot
TELE_BOT_TOKEN="" # Your Telegram Bot Token
TELE_BOT_WEB_LINK="" # ngrok public url in dev mode, public url in production

Start the bot

pnpm start:dev

We are good to go...

Open Telegram and get started. Congratulations!

HAPPYS1NGH / faucet-tg

Telegram Mini App Boilerplate

Tech Stack

Steps (Mini App)

Telegram Bot

Steps (Bot)

About

Languages