This code sample demonstrates how to deploy Telegram Mini Apps and Telegram Bot applications to AWS serverless infrastructure using popular web frameworks with Server-Side Rendering support.
The goal of this sample is to allow developers:
- to deploy Telegram Mini App to the cloud infrastructure within minutes
- to scale the application from 0 to a thousand active users
- to effectively manage infrastructure costs starting from $0/month and grow with pay-as-you-go cost model
- to share a single codebase for frontend, backend and bot
- to speed up development with both vibe-coding and spec-based agentic AI development
- Languages: TypeScript
- Frontend and backend: React Router v7
↗️ in the Framework mode - Telegram Bot framework: grammY
↗️ - Telegram Mini Apps SDK: @tma.js
↗️ - Monorepo management: pnpm
↗️ - Version control: Git
↗️ - Infrastructure as code: AWS CDK v2
↗️ - Cloud infrastructure access: AWS CLI v2
↗️
- Quick Start
- Architecture
- Intended Use-Case
- Register new Telegram Bot
- Configure Telegram Mini App
- Scalability and Cost
- Troubleshooting
- Supported environments
- Clean Up
- License
- Additional Resources
- Register a Telegram Bot using @BotFather and obtain Bot Token.
- Make sure your laptop has AWS CLI v2 and Git CLI and Node.js v22+ installed
- Sign in to AWS Management Console
- Run deployment script on your laptop (MacOS, Linux, WSL)* or in AWS CloudShell:
# login to AWS on your laptop:
#(please skip 'aws login' if you use AWS CloudShell)
aws login
# check prerequisites and deploy Mini App in a guided mode:
npx --yes https://github.com/aws-samples/sample-telegram-miniapp my-app*Note: see Supported environments for details on deployment environment prerequisites
- Compute: AWS Lambda
- Public static content store: Amazon S3
- Session store: Amazon DynamoDB
- Content Delivery Network: Amazon CloudFront
- DDoS protection and application firewall: AWS WAF
- Large Language Model (LLM) inference: Amazon Bedrock
- LLM protection: Amazon Bedrock Guardrails
- Cloud infrastructure management: AWS CloudFormation
- Code repository: AWS CodeCommit
- Code build automation: AWS CodeBuild + Amazon EventBridge
- Logs ingestion and storage: Amazon CloudWatch + Amazon S3
This Mini App sample has absolutely no specific use-case in itself. It has no other purposes but learning by demonstrating integration details.
It's up to you to develop your own Telegram Mini App application with your specific use-case, and we hope that this code sample would help you to get your hands on this topic easier and faster.
Even though it might look like a complete and functional web application, it's just a sample that demonstrates a few useful concepts that help developers to get started with Mini App development quicker:
- Serverless infrastructure for cost management
- Serverless infrastructure for scalability
- Server-Side Rendering in a context of Serverless infrastructure
- React Router v7 Framework mode in a context of Telegram Mini Apps
- Shared backend for both grammY bot framework and React web framework
- Telegram API access through @tma.js SDK to invoke functions like:
- QR code scanner
- Haptic feedback
- Shake detection
- Gyroscope orientation
- GPS location
- "Add to Home Screen" feature
If you haven't done so already, please create your Telegram Bot that would be connected to your Telegram Mini App project later:
- Open Telegram @BotFather in your Telegram client app
- Send
/newbotcommand and follow the prompts to create your bot - Copy the Bot Token (a secret string of format:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
For detailed instructions, see the Telegram Bot FAQ.
After successful deployment to AWS, the deployment script writes all the details that you need for Mini App configuration into docs/REPORT.md file in your repository. You can also generate such report at any time using pnpm run report --output my_file.md
- Find your Miniapp_URL in the deployment report
docs/REPORT.md - Open @BotFather in Telegram client
- Launch @BotFather Mini App by clicking on
Openbutton in lower left corner - Choose your Bot
- Click on Mini Apps menu
- Use your Miniapp_URL to configure two or more ways of launching your Mini App:
- Menu Button
- Main App
- optional: one or more Direct Links
This sample uses AWS Serverless infrastructure that is especially efficient when you just start your Mini App project or launching MVP and looking for:
- pay-as-you-go model for infrastructure costs
- ability to start as low as $0 per month should your application demonstrate small active user base
- ability to scale quickly up to thousands active users per month or millions requests per day should your application demonstrate fast adoption
- ability to migrate to container-based scale-out architectures should your workload grow beyond thousand active users per month.
Please consult official AWS Pricing and AWS Pricing Calculator pages for latest information and details.
Here's a brief extraction on pricing for the main services used in this sample:
| Service | Pricing Model | Source | Brief pricing model |
|---|---|---|---|
| CloudFront (Mini App) | Flat-rate plans | official pricing | Free, Pro, Business, Premium |
| CloudFront (Bot webhook) | Pay-as-you-go | official pricing | $0.085 per GB + $0.01 per 10K HTTPS requests |
| Lambda Function ARM, 256MB | Pay-as-you-go | official pricing | ~$0.20 per million requests + $0.0000034 per second of actual execution time |
| Lambda@Edge x86 | Pay-as-you-go | official pricing | ~$0.60 per million requests + $0.00000625125 per second of actual execution time |
| DynamoDB | On-Demand | official pricing | $0.625 per million write request units, $0.125 per million read request units |
| S3 | Pay-as-you-go | official pricing | $0.023 per GB/month |
| WAF | Flat-rate plans OR Pay-as-you-go | official pricing | $0.60 per million requests + $5/month base + $1/month per rule |
Please check information on AWS Free Tier program.
# Ensure aws CLI has authenticated with your AWS account
aws login
# Ensure AWS credentials are configured
aws sts get-caller-identity
# Bootstrap CDK in your account
pnpm run bootstrapBuild Failures
# Clean and rebuild
pnpm run -r build --force
# Check for TypeScript errors
pnpm --filter "@gui/react" typecheckℹ️ Hint:
For the first time deployment you can just open AWS CloudShell and run the npx command there. This environment has all the tools installed and doesn't require any additional time for preparation.
The following OS/environments should be suitable for sample deployment:
- AWS CloudShell
- MacOS 13.5+
- Ubuntu 22.04+
- Linux supported by Node.js v22+
- WSL 2 on Windows 10+
- Windows 10/11
The following tools have to be installed on your dev machine:
To avoid ongoing charges, delete all deployed resources:
pnpm run destroy-meThis removes:
- data from S3 buckets
- data from DynamoDB tables
- data from CodeCommit repositories
- data from CloudWatch log groups
- S3 Buckets
- DynamoDB Tables
- CodeCommit repositories
- CloudWatch Log Groups
- CloudFront Distributions
- Lambda Functions
- SSM Parameters
- Lambda@Edge function in us-east-1 region (takes time to delete function replication)
- CloudFront distribution that was covered by Flat-Rate Plan (it waits until the end of billing period)
- WebACL in us-east-1 region that was associated with CloudFront distribution that wasn't removed automatically
If you no longer need the bot:
- Open @BotFather
- Send
/deletebot - Select your bot
- Confirm deletion
Check AWS Console to ensure all resources are deleted:
- WAF → WebACLs and IP Sets
- CloudFront → Distributions
- CloudFormation → Stacks
- Lambda → Functions
- CloudWatch → Log Groups
- DynamoDB → Tables
- S3 → Buckets
- CodeCommit → Repositories
- CodeBuild → Projects
This sample code is made available under the MIT-0 license. See the LICENSE file for details.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
