Local Development

The tma dev command starts a local development environment for your Mini App. It handles the dev server and API routes locally.

What tma dev starts

Running tma dev in your project directory spins up the following:

Service	Port	Description
Vite dev server	5173	Your SPA with hot module replacement (HMR)
API server	8787	Miniflare (local Workers runtime) for API routes

tma dev

  SPA       http://localhost:5173
  API       http://localhost:8787/api

  Press Ctrl+C to stop.

How it works

1. Vite dev server starts on port 5173 with HMR for instant feedback during development.

2. API routes: if server/api/index.ts exists, TMA.sh watches the file with esbuild and runs it locally using Miniflare (Cloudflare’s local Workers simulator) on port 8787. The Vite dev server automatically proxies /api/* requests to Miniflare.

Staging bot

If your project already has a production bot serving live users, tma dev will warn you before updating its Web App URL:

  WARNING: Bot @myapp_bot is in production with active users.
  Changing its Web App URL will affect all users.

  Create a staging bot instead? (recommended) [Y/n]

Selecting Y walks you through creating a staging bot via BotFather. The staging bot is saved to your project configuration and used for all future tma dev sessions. Your production bot remains untouched.

You can also register a staging bot manually:

tma bot register

The command prompts interactively for bot details.

Local KV persistence

KV data written during local development is persisted to disk at .tma/kv-data/ in your project directory. This means your KV state survives restarts of tma dev.

my-app/
  .tma/
    kv-data/        # Local KV persistence
    config.json     # Project configuration
  server/
    api/
      index.ts
  src/
    ...

To reset local KV data, delete the .tma/kv-data/ directory.

Environment variables

During local development, environment variables scoped to the development environment are loaded automatically. You can also place a .env file in your project root:

.env

DATABASE_URL=postgres://localhost:5432/myapp
BOT_TOKEN=123456:ABC-DEF

The .env file is used as a fallback when a variable is not set in the dashboard for the development environment. The .env file is git-ignored by default.

See Environment Variables for more details.

Debugging API routes

API route logs are printed to the same terminal as the dev server. Use console.log in your API handlers during development:

app.get('/api/debug', async (c) => {
  const data = await c.env.KV.get('key', 'json');
  console.log('KV data:', data);
  return c.json(data);
});

Miniflare prints logs alongside the Vite dev server output for a unified view of both client and server activity.