This template demonstrates how developers can implement a web application on the Telegram Mini Apps platform using the following technologies and libraries:
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.
If you have just cloned this template, you should install the project dependencies using the command:
pnpm installThis 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.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.
To run a script, use the pnpm run command:
pnpm run {script}
# Example: pnpm run buildBefore you start, make sure you have already created a Telegram Bot. Here is a comprehensive guide on how to do it.
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 devAfter this, you will see a similar message in your terminal:
▲ Next.js 14.2.3
- Local: http://localhost:3000
✓ Starting...
✓ Ready in 2.9sTo 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.
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.4sVisiting 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.
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.