create-ton-dapp

A CLI wizard for scaffolding TON Telegram Mini Apps with modern tooling.

Quick Start

npx create-ton-dapp my-app
cd my-app
pnpm dev

Features

• Next.js 15 with App Router and React 19
• Tailwind CSS v4 for styling
• TON Connect wallet integration (@tonconnect/ui-react)
• Telegram Mini App SDK (@telegram-apps/sdk-react)
• MongoDB with Mongoose (or native driver)
• TanStack Query for data fetching and caching
• Server Actions for backend logic
• JWT authentication with Telegram validation
• shadcn/ui components (optional)
• ESLint + Prettier with import sorting

Usage

Interactive Mode

npx create-ton-dapp

You'll be prompted for:

• Project name
• MongoDB driver (Mongoose or native)
• shadcn/ui components (yes/no)
• Git initialization (yes/no)

With Options

npx create-ton-dapp my-app [options]

CLI Options

| Option | Description | |--------|-------------| | --database <type> | MongoDB driver: mongoose (default) or native | | --shadcn | Include shadcn/ui components | | --no-shadcn | Skip shadcn/ui components | | --use-npm | Use npm as package manager | | --use-yarn | Use yarn as package manager | | --use-bun | Use bun as package manager | | --skip-git | Skip git initialization | | --skip-install | Skip dependency installation | | -y, --yes | Use defaults without prompting |

Examples

# Interactive setup
npx create-ton-dapp

# Quick start with all defaults (includes shadcn)
npx create-ton-dapp my-app -y

# Without shadcn/ui
npx create-ton-dapp my-app -y --no-shadcn

# With native MongoDB driver and npm
npx create-ton-dapp my-app --database native --use-npm

# Skip git and dependency installation
npx create-ton-dapp my-app --skip-git --skip-install

Generated Project Structure

my-app/
├── public/
│   └── tonconnect-manifest.json    # TON Connect configuration
├── src/
│   ├── app/
│   │   ├── globals.css             # Tailwind styles
│   │   ├── layout.tsx              # Root layout with providers
│   │   ├── page.tsx                # Home page
│   │   └── providers.tsx           # TMA + TON + TanStack Query providers
│   ├── components/
│   │   ├── tma/                    # Telegram Mini App components
│   │   ├── ton/                    # TON Connect components
│   │   └── ui/                     # shadcn/ui components (if enabled)
│   ├── hooks/
│   │   ├── use-telegram-auth.ts    # Auth mutation hook
│   │   ├── use-telegram-mock.ts    # Dev environment mock
│   │   └── use-user.ts             # User data hooks
│   ├── lib/
│   │   ├── actions/                # Server Actions
│   │   │   ├── auth.ts             # Telegram authentication
│   │   │   └── user.ts             # User CRUD operations
│   │   ├── auth.ts                 # JWT utilities
│   │   ├── mongodb.ts              # Database connection
│   │   └── utils.ts                # Utilities (if shadcn enabled)
│   ├── models/
│   │   └── user.ts                 # Mongoose User model
│   └── types/
│       └── index.ts                # TypeScript types
├── .env.example                    # Environment variables template
├── .eslintrc.json
├── .prettierrc
├── components.json                 # shadcn config (if enabled)
├── next.config.ts
├── package.json
├── postcss.config.mjs
└── tsconfig.json

Configuration

After creating your project, configure the environment variables:

cp .env.example .env.local

Edit .env.local:

# Telegram Bot Token (from @BotFather)
TELEGRAM_BOT_TOKEN=your_bot_token

# MongoDB Connection String
MONGODB_URI=mongodb://localhost:27017/your_db

# JWT Secret (generate a random string)
JWT_SECRET=your_secret_key

# App URL (for TON Connect manifest)
NEXT_PUBLIC_APP_URL=https://your-app.com

TON Connect Setup

Update public/tonconnect-manifest.json with your app details:

{
  "url": "https://your-app.com",
  "name": "Your App Name",
  "iconUrl": "https://your-app.com/icon.png"
}

Adding More shadcn/ui Components

If you enabled shadcn/ui, you can add more components:

npx shadcn@latest add toast
npx shadcn@latest add dropdown-menu
npx shadcn@latest add form

Development

# Start development server
pnpm dev

# Build for production
pnpm build

# Run linting
pnpm lint

How Authentication Works

1. User opens the Mini App in Telegram
2. The TMA SDK provides initDataRaw containing user info
3. authenticateTelegram server action validates the data
4. If valid, user is created/updated in MongoDB
5. JWT token is returned for subsequent requests

// Example usage in a component
import { useTelegramAuth } from '@/hooks/use-telegram-auth';

function MyComponent() {
  const { mutate: authenticate, data, isPending } = useTelegramAuth();

  // Authentication happens automatically on mount
  // See src/app/page.tsx for the full implementation
}

Tech Stack

| Category | Technology | |----------|------------| | Framework | Next.js 15 (App Router) | | Language | TypeScript | | Styling | Tailwind CSS v4 | | UI Components | shadcn/ui (optional) | | State Management | TanStack Query | | Database | MongoDB + Mongoose | | Authentication | JWT + Telegram validation | | Wallet | TON Connect | | Mini App SDK | @telegram-apps/sdk-react |

License

MIT