Telegram Web K uses pnpm as its package manager (enforced via aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/TelegramOrg/Telegram-web-k/llms.txt
Use this file to discover all available pages before exploring further.
preinstall hook — npm install and yarn will not work). Before you begin, make sure you have Node.js 18+ and pnpm 9+ installed. You will also need a Telegram API ID and hash, which you can get for free from my.telegram.org in under a minute.
Prerequisites:
- Node.js 18 or higher
- pnpm 9.15 or higher (
npm install -g pnpm) - A Telegram account to obtain API credentials
Local setup
Install dependencies
Install all dependencies with pnpm. The
preinstall script enforces pnpm, so other package managers will fail immediately:Configure your API credentials
Obtain a Telegram API ID and hash from my.telegram.org:Open
- Log in with your Telegram phone number.
- Go to API development tools.
- Create a new application — the name and platform can be anything.
- Copy your App api_id and App api_hash.
.env.local.example file is empty by default; Vite will auto-copy it to .env.local on first run, but you can create it manually:.env.local and set your credentials:Start the development server
Start Vite in development mode with hot module replacement:The server starts on http://localhost:8080 by default. The terminal will show the local URL once the build completes.
Open the app in your browser
Navigate to http://localhost:8080 and sign in with your Telegram account. The dev server includes source maps and live reload — changes to TypeScript and SCSS files are applied without a full page refresh.
Available scripts
The following scripts are defined inpackage.json:
| Script | Command | Description |
|---|---|---|
start | pnpm start | Start the Vite dev server with HMR on port 8080 |
build | pnpm build | Generate changelog then produce a minified production build in public/ |
serve | pnpm serve | Build then serve the production build with Node.js |
test | pnpm test | Run the Vitest test suite |
lint | pnpm lint | Lint all TypeScript files under src/ with ESLint |
generate-changelog | pnpm generate-changelog | Regenerate the changelog from commit history |
generate-icons | pnpm generate-icons | Rebuild the icon font from IcoMoon sources |
watch-lang | pnpm watch-lang | Watch and apply language pack changes during development |
Running in Docker
Docker is the recommended approach when you want a clean, reproducible environment or when you are preparing a production image.Development with Docker
Start the dev container
Production with Docker
Start the production nginx container
Debugging query parameters
Append these query parameters to the local URL to change the client’s behavior at runtime. They are parsed bysrc/config/modes.ts on page load.
| Parameter | Example URL | Effect |
|---|---|---|
test=1 | http://localhost:8080/?test=1 | Connect to Telegram’s test data centers instead of production |
debug=1 | http://localhost:8080/?debug=1 | Enable verbose logging in the browser console |
noSharedWorker=1 | http://localhost:8080/?noSharedWorker=1 | Disable the Shared Worker — useful for inspecting network calls per tab |
noServiceWorker=1 | http://localhost:8080/?noServiceWorker=1 | Disable the Service Worker — helpful when debugging push or caching issues |
http=1 | http://localhost:8080/?http=1 | Force HTTPS transport for MTProto instead of WebSocket |
Taking local storage snapshots
Thesnapshot-server mini-app in the repository lets you export and import the client’s local storage and IndexedDB state. This is useful for reproducing bugs without needing the original account. See ./snapshot-server/README.md for usage instructions.
Next steps
Configuration
All environment variables, app config fields, and runtime modes explained.
Architecture
How workers, managers, and the MTProto layer fit together.
Debugging
Dev tools, global class bindings, icon library preview, and snapshot server.
Docker deployment
Build and run production Docker images for self-hosting.