Quick Start
Scaffold and run your first Use Botify Telegram bot in under a minute.
Prerequisites
- Node.js
>=24.0.0— Use Botify relies on native ESM andprocess.loadEnvFile()for zero-dependency.envloading. - A Telegram Bot Token — Create a bot via @BotFather and copy the token.
- A package manager —
pnpm(recommended),npm,bun, oryarn.
1. Scaffold Your Bot
Run the interactive CLI with your preferred package manager:
pnpm create use-botifyOr skip the interactive prompts and scaffold with defaults:
pnpm create use-botify my-bot --yesDuring interactive setup, the CLI configures:
- Project directory (or
.for the current folder) - Source layout (
src/directory or root-level files) - Import alias (defaults to
@/*) - Optional modules — Admin panel (
ADMIN_IDS), Developer icon tools (DEVELOPER_IDS), and Image caching plugin - Package manager, dependency install, and git init
2. Configure Environment Variables
Copy .env.example to .env inside your new project:
cd my-bot
cp .env.example .envFill in your token and optional user IDs:
BOT_TOKEN=123456789:your-botfather-token
NODE_ENV=development
# Optional: comma-separated Telegram user IDs
ADMIN_IDS=
DEVELOPER_IDS=Environment variables are parsed and validated on startup via Zod in
src/env.ts. Missing or malformed values fail fast before polling starts.
3. Start Development Mode
pnpm devIn development mode (NODE_ENV=development), Use Botify starts:
@use-botify/core— grammY bot runtime with structured logging and graceful shutdown.@use-botify/tooling/hmr— Vite SSR watcher that hot-reloads files insidesrc/features/without restarting Telegram polling.@use-botify/tooling/codegen— Automatically regeneratessrc/generated/routes.d.tswhenever routes change.
Generated Project Structure
With default options (--yes), create-use-botify generates:
my-bot/
├── src/
│ ├── features/
│ │ ├── (admin)/
│ │ │ └── panel/
│ │ │ ├── command.ts # /panel
│ │ │ └── close.callback.ts # panel:close
│ │ ├── (developer)/
│ │ │ ├── add_icon/command.ts # /add_icon
│ │ │ ├── list_icons/command.ts # /list_icons
│ │ │ └── remove_icon/command.ts # /remove_icon
│ │ └── start/
│ │ ├── command.ts # /start
│ │ └── ping.callback.ts # start:ping
│ ├── generated/
│ │ └── routes.d.ts # auto-generated route union types
│ ├── lib/
│ │ ├── access.ts # isAdmin() & isDeveloper() guards
│ │ └── icons.ts # iconStore & iconTools plugin
│ ├── registry/
│ │ └── icons.registry.json # persisted custom Telegram emojis
│ ├── env.ts # Zod environment validation
│ └── main.ts # bot bootstrap & HMR wiring
├── .env.example
├── biome.json
├── package.json
└── tsconfig.jsonProduction Build
Compile TypeScript to dist/ and boot without Vite overhead:
pnpm build
pnpm startWhen NODE_ENV=production, main.ts bypasses the Vite HMR watcher and mounts createFsRouter directly.