โ ๏ธ Please, avoid using vanilla JavaScript if possible on Telegram Mini Apps platform. It is better to use ES modules at least.
This example shows how developer could use Vanilla JavaScript to start developing at Telegram Mini Apps platform.
This template demonstrates how developers can implement an application on the Telegram Mini Apps platform using the following technologies and libraries
This boilerplate was created using pnpm. Therefore, it is required to use it for this project as well.
If you have just cloned this template, you should install the project dependencies using the command:
pnpm install
This project contains the following scripts:
serve
. Runs the HTTP server to serve./dist/index.html
.tunnel
. Runs tunnel to locally launched HTTP server.
tunnel
command will return a URL which has to be used by @BotFather. Bind
it to your Mini App and open the application.
To run a script, use the pnpm run
command:
pnpm run {script}
# Example: pnpm run serve
Before 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 serve ./dist/index.html
, use the serve
script:
pnpm run serve
After this, you will see a similar message in your terminal:
Serving!
- Local: http://localhost:3000
- Network: http://192.168.0.117:3000
Here, you can see the Local
link, available locally, and Network
links accessible to all
devices in the same network with the current device.
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 SDK, are not intended for use outside of 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.
Run next script:
pnpm run tunnel
After this, you will see a similar message in your terminal:
your url is: https://odd-yaks-smash.loca.lt
Once the application is displayed correctly, submit one of the Network
links 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.
This boilerplate uses GitHub Pages as the way to host the application externally. GitHub Pages provides a CDN which will let your users receive the application rapidly. Alternatively, you could use such services as Heroku or Vercel.
This boilerplate uses the gh-pages tool, which allows deploying your application right from your PC.
Before running the deployment process, ensure that you have done the following:
- Replaced the
homepage
value inpackage.json
. The GitHub Pages deploy tool uses this value to determine the related GitHub project.
For instance, if your GitHub username is telegram-mini-apps
and the repository name
is is-awesome
, the value in the homepage
field should be the following:
{
"homepage": "https://telegram-mini-apps.github.io/is-awesome"
}
You can find more information on configuring the deployment in the gh-pages
docs.
Then, run the deployment process, using the deploy
script:
pnpm run deploy
After the deployment completed successfully, visit the page with data according to your username and repository name. Here is the page link example using the data mentioned above: https://telegram-mini-apps.github.io/is-awesome
To simplify the deployment process, this template includes a
pre-configured GitHub workflow that automatically
deploys the project when changes are pushed to the master
branch.
To enable this workflow, create a new environment (or edit the existing one) in the GitHub
repository settings and name it github-pages
. Then, add the master
branch to the list of
deployment branches.
You can find the environment settings using this
URL: https://github.com/{username}/{repository}/settings/environments
.
In case, you don't want to do it automatically, or you don't use GitHub as the project codebase,
remove the .github
directory.
Alternatively, developers can configure automatic deployment using the GitHub web interface. To do
this, follow the link: https://github.com/{username}/{repository}/settings/pages
.
This boilerplate utilizes the TON Connect project to demonstrate how developers can integrate functionality related to TON cryptocurrency.
The TON Connect manifest used in this boilerplate is stored in the dist
folder, where all
publicly accessible static files are located. Remember
to configure this file according to your
project's information.