Telegram Mini Apps Next.js Template

This template demonstrates how developers can implement a web application on the Telegram Mini Apps platform using the following technologies and libraries:

• Next.js
• TypeScript
• TON Connect
• @telegram-apps SDK
• Telegram UI

The template was created using pnpm. Therefore, it is required to use it for this project as well. Using other package managers, you will receive a corresponding error.

Install Dependencies

If you have just cloned this template, you should install the project dependencies using the command:

pnpm install

Scripts

This project contains the following scripts:

• dev. Runs the application in development mode.
• dev:https. Runs the application in development mode using self-signed SSL certificate.
• all:build. Builds the application for production.
• start. Starts the Next.js server in production mode.
• lint. Runs eslint to ensure the code quality meets the required standards.
• listener. Runs the PigShop event listener as a standalone process with auto-restart.

PigShop Event Listener

The listener script runs a standalone process that monitors the PigShop smart contract for blockchain events and processes them accordingly. This should be run as a separate process from the main application.

What it listens to:

• UpgradePig: When a user upgrades their pig level
• PigApprovalEvent: When a pig upgrade is approved by the contract
• PigCreationEvent: When a new pig NFT is created
• WithdrawFromPigEvent: When a user withdraws funds from their pig

How it reacts to events:

• UpgradePig:
  • Checks for duplicate purchases
  • Updates user tree structure if needed
  • Sends pig approval messages to bounty hunters
  • Initializes transaction history
• PigApprovalEvent:
  • Updates bounty hunter balances (piggy_bank_balance)
  • Updates user's current pig level
  • Updates transaction history status
  • Updates referral rewards history
• PigCreationEvent:
  • Updates user's pig NFT address
• WithdrawFromPigEvent:
  • Updates user's piggy bank balance

To run the listener:

pnpm run listener

Reliability features:

• Built-in auto-restart on crashes with 5-second delays
• Maximum 10 restart attempts to prevent infinite loops
• Graceful shutdown handling (SIGINT, SIGTERM)
• Comprehensive error logging
• Uncaught exception handling
• Continuous monitoring with 2-second polling intervals

To run a script, use the pnpm run command:

pnpm run {script}
# Example: pnpm run build

Create Bot and Mini App

Before you start, make sure you have already created a Telegram Bot. Here is a comprehensive guide on how to do it.

Run

Although Mini Apps are designed to be opened within Telegram applications, you can still develop and test them outside of Telegram during the development process.

To run the application in the development mode, use the dev script:

pnpm run dev

To run the application in the production mode, use the start script:

pnpm run start

After this, you will see a similar message in your terminal:

▲ Next.js 14.2.3
- Local:        http://localhost:3000

✓ Starting...
✓ Ready in 2.9s

To view the application, you need to open the Local link (http://localhost:3000 in this example) in your browser.

It is important to note that some libraries in this template, such as @telegram-apps/sdk, are not intended for use outside of Telegram.

Nevertheless, they appear to function properly. This is because the src/hooks/useTelegramMock.ts file, which is imported in the application's Root component, employs the mockTelegramEnv function to simulate the Telegram environment. This trick convinces the application that it is running in a Telegram-based environment. Therefore, be cautious not to use this function in production mode unless you fully understand its implications.

Run Inside Telegram

Although it is possible to run the application outside of Telegram, it is recommended to develop it within Telegram for the most accurate representation of its real-world functionality.

To run the application inside Telegram, @BotFather requires an HTTPS link.

This template already provides a solution.

To retrieve a link with the HTTPS protocol, consider using the dev:https script:

$ pnpm run dev:https

▲ Next.js 14.2.3
- Local:        https://localhost:3000

✓ Starting...
✓ Ready in 2.4s

Visiting the Local link (https://localhost:3000 in this example) in your browser, you will see the following warning:

This browser warning is normal and can be safely ignored as long as the site is secure. Click the Proceed to localhost (unsafe) button to continue and view the application.

Once the application is displayed correctly, submit the link https://127.0.0.1:3000 (https://localhost:3000 is considered as invalid by BotFather) as the Mini App link to @BotFather. Then, navigate to https://web.telegram.org/k/, find your bot, and launch the Telegram Mini App. This approach provides the full development experience.

Deploy

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out the Next.js deployment documentation for more details.

Useful Links

• Platform documentation
• @telegram-apps/sdk-react documentation
• Telegram developers community chate: pnpm dev

Swagger

after running the service on the dev mode or prd mode go to

Requirements

• next-js >= v14

• node >= v20

• url after running the service on the dev mode or prd mode go to:

• http://localhost:3000/api-doc

Database setup from scratch

# login to supabase CLI
npx supabase login
# link the project (you can see project ref in Project Settings on supabase , it is called Project ID)
# this will also require your DB password. if you don't know it you can restore password in Project Settings -> Database section on supabase website.
npx supabase link --project-ref <your-project-ref>
# now when you set up the supabase CLI, run migration to set up empty tables

npx supabase db push