Complete typescript template (#2)

* Install deps

* Implement TON Connect page

* Update readme, add gh-pages

* Fixes from checks

* Format code

* Fix README commands

---------

Co-authored-by: Nishcheta Dmitry <[email protected]>

.eslintrc.cjs

@@ -0,0 +1,32 @@
+module.exports = {
+    env: {
+      browser: true,
+      es2021: true
+    },
+    extends: [
+      'eslint:recommended',
+      'plugin:@typescript-eslint/recommended',
+    ],
+    overrides: [
+      {
+        env: {
+          node: true
+        },
+        files: [
+          '.eslintrc.{js,cjs}'
+        ],
+        parserOptions: {
+          sourceType: 'script'
+        }
+      }
+    ],
+    parser: '@typescript-eslint/parser',
+    parserOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module'
+    },
+    plugins: [
+      '@typescript-eslint'
+    ],
+    rules: {}
+  };

.github/workflows/github-pages-deploy.yml

@@ -0,0 +1,61 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ['master']
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: 'pages'
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        id: pnpm-install
+        with:
+          version: 8
+          run_install: true
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          # Upload dist repository
+          path: './dist'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -3,19 +3,229 @@
 This example shows how developer could use TypeScript along with Vite to start developing at
 Telegram Mini Apps platform.
 
-> Don't forget, that you should open this application inside Telegram. Otherwise, you will get an
-> error related to the wrong environment.
+This template demonstrates how developers can implement an application on the Telegram
+Mini Apps platform using the following technologies and libraries
 
-## Trying it out
+- [TypeScript](https://www.typescriptlang.org/)
+- [TON Connect](https://docs.ton.org/develop/dapps/ton-connect/overview)
+- [@telegram-apps SDK](https://docs.telegram-mini-apps.com/packages/telegram-apps-sdk)
+- [Vite](https://vitejs.dev/)
 
-First of all, install all dependencies:
+> This boilerplate was created using [pnpm](https://pnpm.io/). Therefore, it is required to use
+> it for this project as well.
 
-```bash
-pnpm i
+## Install Dependencies
+
+If you have just cloned this template, you should install the project dependencies using the
+command:
+
+```Bash
+pnpm install
+```
+
+## Scripts
+
+This project contains the following scripts:
+
+- `dev`. Runs the application in development mode.
+- `build`. Builds the application for production.
+- `lint`. Runs [eslint](https://eslint.org/) to ensure the code quality meets the required
+  standards.
+- `deploy`. Deploys the application to GitHub Pages.
+
+To run a script, use the `pnpm run` command:
+
+```Bash
+pnpm run {script}
+# Example: pnpm run build
 ```
 
-Then, just run dev server and follow the link in console:
+## Create Bot and Mini App
+
+Before you start, make sure you have already created a Telegram Bot. Here is
+a [comprehensive guide](https://docs.telegram-mini-apps.com/platform/creating-new-app) on how to
+do it.
+
+## Run
+
+Although Mini Apps are designed to be opened
+within [Telegram applications](https://docs.telegram-mini-apps.com/platform/about#supported-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:
 
 ```bash
 pnpm run dev
 ```
+
+After this, you will see a similar message in your terminal:
+
+```bash
+VITE v5.2.12  ready in 237 ms
+
+➜  Local:   http://localhost:5173/typescript-template
+➜  Network: http://172.18.16.1:5173/typescript-template
+➜  Network: http://172.19.32.1:5173/typescript-template
+➜  Network: http://192.168.0.171:5173/typescript-template
+➜  press h + enter to show help
+```
+
+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:5173/typescript-template` 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/mockEnv.ts` file, which is
+imported in the application's entry point (`src/index.ts`), 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](https://t.me/botfather) requires an HTTPS link.
+
+This template already provides a solution.
+
+Navigate to the `vite.config.ts` file and uncomment the usage of the `basicSsl` function. This
+function utilizes
+the [@vitejs/plugin-basic-ssl](https://www.npmjs.com/package/@vitejs/plugin-basic-ssl) plugin, which
+enables the creation of an HTTPS link. Note that this plugin generates a self-signed certificate,
+which browsers will recognize as unsafe, resulting in a warning when accessing the app.
+
+After uncommenting the function, run the `dev` script again and observe the output in your terminal:
+
+```bash
+VITE v5.2.12  ready in 265 ms
+
+➜  Local:   https://localhost:5173/typescript-template
+➜  Network: https://172.18.16.1:5173/typescript-template
+➜  Network: https://172.19.32.1:5173/typescript-template
+➜  Network: https://192.168.0.171:5173/typescript-template
+➜  press h + enter to show help
+```
+
+Visiting the `Local` link (`https://localhost:5173/typescript-template` in this example) in your
+browser, you will see the following warning:
+
+![SSL Warning](assets/ssl-warning.png)
+
+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 one of the `Network` links as the Mini App link
+to [@BotFather](https://t.me/botfather). Then, navigate
+to [https://web.telegram.org/k/](https://web.telegram.org/k/), find your bot, and launch the
+Telegram Mini App. This approach provides the full development experience.
+
+> **Important**
+>
+> Because we are using self-signed SSL certificates, the Android and iOS Telegram applications will
+> not be able to display the application. These operating systems enforce stricter security
+> measures, preventing the Mini App from loading. To address this issue, refer
+> to [this guide](https://docs.telegram-mini-apps.com/platform/getting-app-link#remote).
+
+## Deploy
+
+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](https://www.heroku.com/) or [Vercel](https://vercel.com).
+
+### Manual Deployment
+
+This boilerplate uses the [gh-pages](https://www.npmjs.com/package/gh-pages) tool, which allows
+deploying your application right from your PC.
+
+#### Configuring
+
+Before running the deployment process, ensure that you have done the following:
+
+1. Replaced the `homepage` value in `package.json`. The GitHub Pages deploy tool uses this value to
+   determine the related GitHub project.
+2. Replaced the `base` value in `vite.config.ts` and have set it to the name of your GitHub
+   repository. Vite will use this value when creating paths to static assets.
+
+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:
+
+```json
+{
+  "homepage": "https://telegram-mini-apps.github.io/is-awesome"
+}
+```
+
+And `vite.config.ts` should have this content:
+
+```ts
+export default defineConfig({
+  base: '/is-awesome/',
+  // ...
+});
+```
+
+You can find more information on configuring the deployment in the `gh-pages`
+[docs](https://github.com/tschaub/gh-pages?tab=readme-ov-file#github-pages-project-sites).
+
+#### Before Deploying
+
+Before deploying the application, make sure that you've built it and going to deploy the fresh
+static files:
+
+```bash
+pnpm run build
+```
+
+Then, run the deployment process, using the `deploy` script:
+
+```Bash
+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
+
+### GitHub Workflow
+
+To simplify the deployment process, this template includes a
+pre-configured [GitHub workflow](.github/workflows/github-pages-deploy.yml) 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`.
+
+![img.png](.github/deployment-branches.png)
+
+In case, you don't want to do it automatically, or you don't use GitHub as the project codebase,
+remove the `.github` directory.
+
+### GitHub Web Interface
+
+Alternatively, developers can configure automatic deployment using the GitHub web interface. To do
+this, follow the link: `https://github.com/{username}/{repository}/settings/pages`.
+
+## TON Connect
+
+This boilerplate utilizes the [TON Connect](https://docs.ton.org/develop/dapps/ton-connect/overview)
+project to demonstrate how developers can integrate functionality related to TON cryptocurrency.
+
+The TON Connect manifest used in this boilerplate is stored in the `public` folder, where all
+publicly accessible static files are located. Remember
+to [configure](https://docs.ton.org/develop/dapps/ton-connect/manifest) this file according to your
+project's information.
+
+## Useful Links
+
+- [Platform documentation](https://docs.telegram-mini-apps.com/)
+- [Telegram developers community chat](https://t.me/devs)

index.html

@@ -1,14 +1,21 @@
-<html>
+<html lang="en">
 <head>
-  <meta charset="UTF-8">
+  <meta charset="utf-8">
   <meta
     name="viewport"
     content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
   >
   <meta http-equiv="X-UA-Compatible" content="ie=edge">
   <title>Telegram Mini Apps TypeScript Example</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link
+    href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap"
+    rel="stylesheet"
+  >
 </head>
 <body>
+  <noscript>You need to enable JavaScript to run this app.</noscript>
   <div id="root"></div>
   <script src="src/index.ts" type="module"></script>
 </body>

package.json

@@ -5,24 +5,34 @@
   "version": "0.0.1",
   "main": "index.js",
   "type": "module",
+  "homepage": "https://telegram-mini-apps.github.io/typescript-template",
   "scripts": {
+    "deploy": "gh-pages -d dist",
     "dev": "vite",
     "build": "tsc && vite build",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "lint": "eslint --ext .ts,.tsx --report-unused-disable-directives --max-warnings 0 src/",
+    "lint:fix": "eslint --ext .ts,.tsx --report-unused-disable-directives --max-warnings 0 --fix src/",
     "preview": "vite preview"
   },
   "keywords": [],
   "author": "Vladislav Kibenko",
   "license": "MIT",
   "devDependencies": {
+    "@eslint/js": "^9.2.0",
     "@types/jquery": "^3.5.30",
+    "@typescript-eslint/eslint-plugin": "^7.8.0",
+    "@typescript-eslint/parser": "^7.8.0",
     "@vitejs/plugin-basic-ssl": "^1.1.0",
+    "eslint": "^8.57.0",
+    "gh-pages": "^6.1.1",
     "typescript": "^5.5.3",
+    "typescript-eslint": "^7.8.0",
     "vite": "^5.3.2",
     "vite-tsconfig-paths": "^4.3.2"
   },
   "dependencies": {
     "@telegram-apps/sdk": "^1.1.1",
+    "@tonconnect/ui": "^2.0.6",
     "eruda": "^3.0.1",
     "jquery": "^3.7.1"
   }