1
1
# Telegram Mini Apps React Template
2
2
3
- This template demonstrates how developers can implement a single-page application on the Telegram
4
- Mini Apps platform using the following technologies and libraries:
3
+ This template demonstrates how developers can implement a single-page
4
+ application on the Telegram Mini Apps platform using the following technologies
5
+ and libraries:
5
6
6
7
- [ React] ( https://react.dev/ )
7
8
- [ TypeScript] ( https://www.typescriptlang.org/ )
@@ -10,13 +11,14 @@ Mini Apps platform using the following technologies and libraries:
10
11
- [ Telegram UI] ( https://github.com/Telegram-Mini-Apps/TelegramUI )
11
12
- [ Vite] ( https://vitejs.dev/ )
12
13
13
- > The template was created using [ npm] ( https://www.npmjs.com/ ) . Therefore, it is required to use
14
- > it for this project as well. Using other package managers, you will receive a corresponding error.
14
+ > The template was created using [ npm] ( https://www.npmjs.com/ ) . Therefore, it is
15
+ > required to use it for this project as well. Using other package managers, you
16
+ > will receive a corresponding error.
15
17
16
18
## Install Dependencies
17
19
18
- If you have just cloned this template, you should install the project dependencies using the
19
- command:
20
+ If you have just cloned this template, you should install the project
21
+ dependencies using the command:
20
22
21
23
``` Bash
22
24
npm install
@@ -28,8 +30,8 @@ This project contains the following scripts:
28
30
29
31
- ` dev ` . Runs the application in development mode.
30
32
- ` build ` . Builds the application for production.
31
- - ` lint ` . Runs [ eslint] ( https://eslint.org/ ) to ensure the code quality meets the required
32
- standards.
33
+ - ` lint ` . Runs [ eslint] ( https://eslint.org/ ) to ensure the code quality meets
34
+ the required standards.
33
35
- ` deploy ` . Deploys the application to GitHub Pages.
34
36
35
37
To run a script, use the ` npm run ` command:
@@ -42,14 +44,15 @@ npm run {script}
42
44
## Create Bot and Mini App
43
45
44
46
Before you start, make sure you have already created a Telegram Bot. Here is
45
- a [ comprehensive guide] ( https://docs.telegram-mini-apps.com/platform/creating-new-app ) on how to
46
- do it.
47
+ a [ comprehensive guide] ( https://docs.telegram-mini-apps.com/platform/creating-new-app )
48
+ on how to do it.
47
49
48
50
## Run
49
51
50
52
Although Mini Apps are designed to be opened
51
53
within [ Telegram applications] ( https://docs.telegram-mini-apps.com/platform/about#supported-applications ) ,
52
- you can still develop and test them outside of Telegram during the development process.
54
+ you can still develop and test them outside of Telegram during the development
55
+ process.
53
56
54
57
To run the application in the development mode, use the ` dev ` script:
55
58
@@ -62,99 +65,64 @@ After this, you will see a similar message in your terminal:
62
65
``` bash
63
66
VITE v5.2.12 ready in 237 ms
64
67
65
- ➜ Local: http://localhost:5173/reactjs-template
66
- ➜ Network: http://172.18.16.1:5173/reactjs-template
67
- ➜ Network: http://172.19.32.1:5173/reactjs-template
68
- ➜ Network: http://192.168.0.171:5173/reactjs-template
69
- ➜ press h + enter to show help
70
- ```
71
-
72
- Here, you can see the ` Local ` link, available locally, and ` Network ` links accessible to all
73
- devices in the same network with the current device.
74
-
75
- To view the application, you need to open the ` Local `
76
- link (` http://localhost:5173/reactjs-template ` in this example) in your browser:
77
-
78
- ![ Application] ( assets/application.png )
79
-
80
- It is important to note that some libraries in this template, such as ` @telegram-apps/sdk ` , are not
81
- intended for use outside of Telegram.
82
-
83
- Nevertheless, they appear to function properly. This is because the ` src/mockEnv.ts ` file, which is
84
- imported in the application's entry point (` src/index.ts ` ), employs the ` mockTelegramEnv ` function
85
- to simulate the Telegram environment. This trick convinces the application that it is running in a
86
- Telegram-based environment. Therefore, be cautious not to use this function in production mode
87
- unless you fully understand its implications.
88
-
89
- ### Run Inside Telegram
90
-
91
- Although it is possible to run the application outside of Telegram, it is recommended to develop it
92
- within Telegram for the most accurate representation of its real-world functionality.
93
-
94
- To run the application inside Telegram, [ @BotFather ] ( https://t.me/botfather ) requires an HTTPS link.
95
-
96
- This template already provides a solution.
97
-
98
- Navigate to the ` vite.config.ts ` file and uncomment the usage of the ` basicSsl ` function. This
99
- function utilizes
100
- the [ @vitejs/plugin-basic-ssl ] ( https://www.npmjs.com/package/@vitejs/plugin-basic-ssl ) plugin, which
101
- enables the creation of an HTTPS link. Note that this plugin generates a self-signed certificate,
102
- which browsers will recognize as unsafe, resulting in a warning when accessing the app.
103
-
104
- After uncommenting the function, run the ` dev ` script again and observe the output in your terminal:
105
-
106
- ``` bash
107
- VITE v5.2.12 ready in 265 ms
108
-
109
68
➜ Local: https://localhost:5173/reactjs-template
110
69
➜ Network: https://172.18.16.1:5173/reactjs-template
111
70
➜ Network: https://172.19.32.1:5173/reactjs-template
112
71
➜ Network: https://192.168.0.171:5173/reactjs-template
113
72
➜ press h + enter to show help
114
73
```
115
74
116
- Visiting the ` Local ` link ( ` https://localhost:5173/reactjs-template ` in this example) in your
117
- browser, you will see the following warning:
75
+ Here, you can see the ` Local ` link, available locally, and ` Network ` links
76
+ accessible to all devices in the same network with the current device.
118
77
119
- ![ SSL Warning] ( assets/ssl-warning.png )
78
+ To view the application, you need to open the ` Local `
79
+ link (` https://localhost:5173/reactjs-template ` in this example) in your
80
+ browser:
81
+
82
+ ![ Application] ( assets/application.png )
120
83
121
- This browser warning is normal and can be safely ignored as long as the site is secure. Click
122
- the ` Proceed to localhost (unsafe) ` button to continue and view the application .
84
+ It is important to note that some libraries in this template, such as
85
+ ` @telegram-apps/sdk ` , are not intended for use outside of Telegram .
123
86
124
- Once the application is displayed correctly, submit one of the ` Network ` links as the Mini App link
125
- to [ @BotFather ] ( https://t.me/botfather ) . Then, navigate
126
- to [ https://web.telegram.org/k/ ] ( https://web.telegram.org/k/ ) , find your bot, and launch the
127
- Telegram Mini App. This approach provides the full development experience.
87
+ Nevertheless, they appear to function properly. This is because the
88
+ ` src/mockEnv.ts ` file, which is imported in the application's entry point (
89
+ ` src/index.ts ` ), employs the ` mockTelegramEnv ` function to simulate the Telegram
90
+ environment. This trick convinces the application that it is running in a
91
+ Telegram-based environment. Therefore, be cautious not to use this function in
92
+ production mode unless you fully understand its implications.
128
93
129
- > ** Important **
130
- >
131
- > Because we are using self-signed SSL certificates, the Android and iOS Telegram applications will
132
- > not be able to display the application. These operating systems enforce stricter security
133
- > measures, preventing the Mini App from loading. To address this issue, refer
134
- > to [ this guide] ( https://docs.telegram-mini-apps.com/platform/getting-app-link#remote ) .
94
+ > [ !WARNING ]
95
+ > Because we are using self-signed SSL certificates, the Android and iOS
96
+ > Telegram applications will not be able to display the application. These
97
+ > operating systems enforce stricter security measures, preventing the Mini App
98
+ > from loading. To address this issue, refer to
99
+ > [ this guide] ( https://docs.telegram-mini-apps.com/platform/getting-app-link#remote ) .
135
100
136
101
## Deploy
137
102
138
- This boilerplate uses GitHub Pages as the way to host the application externally. GitHub Pages
139
- provides a CDN which will let your users receive the application rapidly. Alternatively, you could
140
- use such services as [ Heroku] ( https://www.heroku.com/ ) or [ Vercel] ( https://vercel.com ) .
103
+ This boilerplate uses GitHub Pages as the way to host the application
104
+ externally. GitHub Pages provides a CDN which will let your users receive the
105
+ application rapidly. Alternatively, you could use such services
106
+ as [ Heroku] ( https://www.heroku.com/ ) or [ Vercel] ( https://vercel.com ) .
141
107
142
108
### Manual Deployment
143
109
144
- This boilerplate uses the [ gh-pages] ( https://www.npmjs.com/package/gh-pages ) tool, which allows
145
- deploying your application right from your PC.
110
+ This boilerplate uses the [ gh-pages] ( https://www.npmjs.com/package/gh-pages )
111
+ tool, which allows deploying your application right from your PC.
146
112
147
113
#### Configuring
148
114
149
115
Before running the deployment process, ensure that you have done the following:
150
116
151
- 1 . Replaced the ` homepage ` value in ` package.json ` . The GitHub Pages deploy tool uses this value to
117
+ 1 . Replaced the ` homepage ` value in ` package.json ` . The GitHub Pages deploy tool
118
+ uses this value to
152
119
determine the related GitHub project.
153
- 2 . Replaced the ` base ` value in ` vite.config.ts ` and have set it to the name of your GitHub
120
+ 2 . Replaced the ` base ` value in ` vite.config.ts ` and have set it to the name of
121
+ your GitHub
154
122
repository. Vite will use this value when creating paths to static assets.
155
123
156
- For instance, if your GitHub username is ` telegram-mini-apps ` and the repository name
157
- is ` is-awesome ` , the value in the ` homepage ` field should be the following:
124
+ For instance, if your GitHub username is ` telegram-mini-apps ` and the repository
125
+ name is ` is-awesome ` , the value in the ` homepage ` field should be the following:
158
126
159
127
``` json
160
128
{
@@ -176,8 +144,8 @@ You can find more information on configuring the deployment in the `gh-pages`
176
144
177
145
#### Before Deploying
178
146
179
- Before deploying the application, make sure that you've built it and going to deploy the fresh
180
- static files:
147
+ Before deploying the application, make sure that you've built it and going to
148
+ deploy the fresh static files:
181
149
182
150
``` bash
183
151
npm run build
@@ -189,42 +157,47 @@ Then, run the deployment process, using the `deploy` script:
189
157
npm run deploy
190
158
```
191
159
192
- After the deployment completed successfully, visit the page with data according to your
193
- username and repository name. Here is the page link example using the data mentioned above:
160
+ After the deployment completed successfully, visit the page with data according
161
+ to your username and repository name. Here is the page link example using the
162
+ data mentioned above:
194
163
https://telegram-mini-apps.github.io/is-awesome
195
164
196
165
### GitHub Workflow
197
166
198
167
To simplify the deployment process, this template includes a
199
- pre-configured [ GitHub workflow] ( .github/workflows/github-pages-deploy.yml ) that automatically
200
- deploys the project when changes are pushed to the ` master ` branch.
168
+ pre-configured [ GitHub workflow] ( .github/workflows/github-pages-deploy.yml ) that
169
+ automatically deploys the project when changes are pushed to the ` master `
170
+ branch.
201
171
202
- To enable this workflow, create a new environment (or edit the existing one) in the GitHub
203
- repository settings and name it ` github-pages ` . Then, add the ` master ` branch to the list of
204
- deployment branches.
172
+ To enable this workflow, create a new environment (or edit the existing one) in
173
+ the GitHub repository settings and name it ` github-pages ` . Then, add the
174
+ ` master ` branch to the list of deployment branches.
205
175
206
176
You can find the environment settings using this
207
177
URL: ` https://github.com/{username}/{repository}/settings/environments ` .
208
178
209
179
![ img.png] ( .github/deployment-branches.png )
210
180
211
- In case, you don't want to do it automatically, or you don't use GitHub as the project codebase,
212
- remove the ` .github ` directory.
181
+ In case, you don't want to do it automatically, or you don't use GitHub as the
182
+ project codebase, remove the ` .github ` directory.
213
183
214
184
### GitHub Web Interface
215
185
216
- Alternatively, developers can configure automatic deployment using the GitHub web interface. To do
217
- this, follow the link: ` https://github.com/{username}/{repository}/settings/pages ` .
186
+ Alternatively, developers can configure automatic deployment using the GitHub
187
+ web interface. To do this, follow the link:
188
+ ` https://github.com/{username}/{repository}/settings/pages ` .
218
189
219
190
## TON Connect
220
191
221
- This boilerplate utilizes the [ TON Connect] ( https://docs.ton.org/develop/dapps/ton-connect/overview )
222
- project to demonstrate how developers can integrate functionality related to TON cryptocurrency.
192
+ This boilerplate utilizes
193
+ the [ TON Connect] ( https://docs.ton.org/develop/dapps/ton-connect/overview )
194
+ project to demonstrate how developers can integrate functionality related to TON
195
+ cryptocurrency.
223
196
224
- The TON Connect manifest used in this boilerplate is stored in the ` public ` folder, where all
225
- publicly accessible static files are located. Remember
226
- to [ configure] ( https://docs.ton.org/develop/dapps/ton-connect/manifest ) this file according to your
227
- project's information.
197
+ The TON Connect manifest used in this boilerplate is stored in the ` public `
198
+ folder, where all publicly accessible static files are located. Remember
199
+ to [ configure] ( https://docs.ton.org/develop/dapps/ton-connect/manifest ) this
200
+ file according to your project's information.
228
201
229
202
## Useful Links
230
203
0 commit comments