Your First Deploy

This walkthrough takes you from an empty directory to a live Telegram Mini App. You will scaffold a project, test it locally, and deploy it to production.

Create and develop locally

1. Scaffold the project. Run tma init and select the Vite React template:

   tma init my-first-app

2. Enter the project directory.

   cd my-first-app

3. Edit your app. Open src/App.tsx and replace the contents with a simple Mini App that greets the user:

   import { useEffect, useState } from "react";
   
   function App() {
     const [name, setName] = useState("there");
   
     useEffect(() => {
       const webapp = window.Telegram?.WebApp;
       if (webapp) {
         webapp.ready();
         const user = webapp.initDataUnsafe?.user;
         if (user?.first_name) {
           setName(user.first_name);
         }
       }
     }, []);
   
     return (
       <main style={{ padding: "2rem", textAlign: "center" }}>
         <h1>Hello, {name}!</h1>
         <p>Your first Telegram Mini App is running.</p>
       </main>
     );
   }
   
   export default App;

4. Start the dev server. The tma dev command starts a local Vite dev server with hot reload:

   tma dev

   You will see output like:

   Local:   http://localhost:5173

5. Test in Telegram. Open your bot in Telegram, tap the menu button (bottom-left), and your app loads inside the Telegram client. Changes you make locally appear instantly via hot module replacement.

Deploy to production

Once you are happy with the app, deploy it to the world.

1. Initialize a Git repo and push to GitHub.

   git init
   git add .
   git commit -m "init"
   git remote add origin https://github.com/your-username/my-first-app.git
   git push -u origin main

2. Connect the repository. Open the TMA.sh dashboard, navigate to your project, and connect your GitHub repository. This installs a GitHub webhook that triggers deployments on every push to main.

3. Push a change to trigger a deploy. Any push to main kicks off an automatic deployment. Your first deploy is already queued from the previous step — check the deployment status in the dashboard or via tma logs.

4. Your app is live. Once the deployment finishes, your Mini App is available at:

   https://my-first-app.tma.sh

   The bot’s Web App URL is automatically updated to point at the production deployment.

What happens during a deploy

When you push to main, TMA.sh runs the following pipeline:

1. GitHub webhook — TMA.sh receives the push event.
2. Build container — a clean environment runs your configured install and build commands (defaults to npm install and npm run build).
3. Upload assets — the build output is uploaded to the global CDN.
4. Update bot URL — the Telegram bot’s Web App URL is pointed at the new deployment.
5. Ready — your app is live and serving traffic.

If you have a server/api/index.ts file, TMA.sh also bundles and deploys your API routes to my-first-app--api.tma.sh.

Deployment statuses

Each deployment moves through these stages:

Status	Meaning
queued	Push received, waiting for a build slot.
building	Dependencies are being installed and the project is being built.
deploying	Build output is being uploaded to the CDN and bot URL is being updated.
ready	Deployment is live and serving traffic.
failed	Something went wrong. Check the build logs with tma logs.
cleaned	Deployment assets have been cleaned up (old deployments).
purged	Deployment has been permanently removed.

Auto-deploy

By default, every push to main triggers a deployment. You can toggle auto-deploy on or off in your project settings on the dashboard.

When auto-deploy is off, use tma deploy to deploy manually.

Next steps

Your Mini App is live. From here, you can:

• Add API routes to handle server-side logic.
• Set up authentication to identify Telegram users.
• Accept payments via TON or Telegram Stars.
• Use KV storage for simple data persistence.
• Configure a custom domain for your app.