{"id":42078,"library":"tele-better-auth","title":"Tele-Better-Auth: Telegram authentication plugin for Better Auth","description":"Tele-Better-Auth (v1.6.4) is a Telegram authentication plugin for Better Auth that supports Login Widget, Mini Apps, and OIDC flows with HMAC-SHA-256 verification. It pairs with better-auth ^1.6.11 and requires Node.js >=22 or runtimes with Web Crypto API. Unlike generic Telegram OAuth wrappers, it handles linking/unlinking accounts, phone number retrieval via OIDC scope, and integrates directly with Better Auth's plugin system for database schema additions. The library is TypeScript-native with 100% test coverage, actively maintained, and uses no node:crypto, making it edge-runtime friendly.","status":"active","version":"1.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/mhbdev/tele-better-auth","tags":["javascript","better-auth","better-auth-plugin","telegram","telegram-login","telegram-mini-apps","authentication","oauth","plugin","typescript"],"install":[{"cmd":"npm install tele-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add tele-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add tele-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the plugin requires Better Auth core to function","package":"better-auth","optional":false}],"imports":[{"note":"ESM-only; CommonJS require will fail due to 'type': 'module' in package.json","wrong":"const telegram = require('tele-better-auth')","symbol":"telegram","correct":"import { telegram } from 'tele-better-auth'"},{"note":"Client-side helper is exported from the /client subpath, not the main entry","wrong":"import { telegramClient } from 'tele-better-auth'","symbol":"telegramClient","correct":"import { telegramClient } from 'tele-better-auth/client'"},{"note":"Server utility is exported from the /server subpath; added in v1.1.0","wrong":"import { userHasTelegramLinked } from 'tele-better-auth'","symbol":"userHasTelegramLinked","correct":"import { userHasTelegramLinked } from 'tele-better-auth/server'"}],"quickstart":{"code":"import { betterAuth } from 'better-auth';\nimport { telegram } from 'tele-better-auth';\n\nexport const auth = betterAuth({\n  plugins: [\n    telegram({\n      botToken: process.env.TELEGRAM_BOT_TOKEN ?? '',\n      botUsername: 'my_bot',\n    }),\n  ],\n});\n\n// Client side:\nimport { createAuthClient } from 'better-auth/client';\nimport { telegramClient } from 'tele-better-auth/client';\n\nexport const authClient = createAuthClient({\n  plugins: [telegramClient()],\n});\n\n// Sign in widget:\nauthClient.initTelegramWidget(\n  'telegram-login-container',\n  { size: 'large', cornerRadius: 20 },\n  async (authData) => {\n    const result = await authClient.signInWithTelegram(authData);\n    if (!result.error) window.location.href = '/dashboard';\n  },\n);","lang":"typescript","description":"Sets up the Telegram plugin on the server, creates an auth client with the client plugin, and demonstrates sign-in via the login widget."},"warnings":[{"fix":"Update better-auth to >=1.6.11","message":"Requires better-auth ^1.6.11; incompatible with older versions.","severity":"breaking","affected_versions":"<1.6.11 for better-auth"},{"fix":"Upgrade Node.js to >=22 or use a runtime like Bun, Deno, or Cloudflare Workers","message":"Requires Node.js >=22 or runtime with full Web Crypto API; older Node versions (e.g., 16, 18, 20) will fail.","severity":"breaking","affected_versions":"<1.0.0 for Node"},{"fix":"Use import { telegramClient } from 'tele-better-auth/client'","message":"Client-side plugin must be imported from 'tele-better-auth/client', not 'tele-better-auth'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Store TELEGRAM_BOT_TOKEN in environment variables; never bundle it in client code","message":"The bot token must be kept secret; exposing it allows anyone to impersonate your bot and sign in as arbitrary users.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the newer widget/button API methods (see README)","message":"The old 'initTelegramLogin' and 'openTelegramLogin' helpers (pre v1.3) have been deprecated in favor of 'initTelegramWidget' and 'renderTelegramLoginButton'.","severity":"deprecated","affected_versions":">=1.3.0"}],"env_vars":null,"search_vec":"'1.6.11':45 '100':91 '22':49 '256':37 'account':64 'activ':94 'addit':83 'api':55 'app':29,122 'auth':4,10,14,23,44,76,110,113 'authent':6,19,123 'better':3,9,13,22,43,75,109,112 'better-auth':42,108 'better-auth-plugin':111 'coverag':93 'crypto':54,100 'databas':81 'direct':73 'edg':104 'edge-runtim':103 'flow':32 'friend':106 'generic':57 'handl':62 'hmac':35 'hmac-sha':34 'integr':72 'javascript':107 'librari':85 'linking/unlinking':63 'login':26,118 'maintain':95 'make':101 'mini':28,121 'nativ':89 'node':99 'node.js':48 'number':66 'oauth':59,124 'oidc':31,69 'pair':40 'phone':65 'plugin':7,20,78,114,125 'requir':47 'retriev':67 'runtim':51,105 'schema':82 'scope':70 'sha':36 'support':25 'system':79 'tele':2,12 'tele-better-auth':1,11 'telegram':5,18,58,115,117,120 'telegram-login':116 'telegram-mini-app':119 'test':92 'typescript':88,126 'typescript-n':87 'unlik':56 'use':97 'v1.6.4':15 'verif':38 'via':68 'web':53 'widget':27 'wrapper':60","created_at":"2026-06-04T18:55:30.693294+00:00","updated_at":"2026-06-04T18:55:30.693294+00:00","problems":[{"fix":"Update better-auth to ^1.6.11: npm install better-auth@^1.6.11","cause":"Incompatible better-auth version (e.g., <1.6.11) or wrong peer dependency.","error":"Error: Package 'tele-better-auth' is not compatible with this version of better-auth."},{"fix":"Ensure you call telegramClient() in createAuthClient plugins: import { telegramClient } from 'tele-better-auth/client' and add it.","cause":"Forgot to add telegramClient() plugin to the client or imported from wrong path.","error":"TypeError: Cannot read properties of undefined (reading 'initTelegramWidget')"},{"fix":"Upgrade to Node >=22 or use Bun/Deno/Cloudflare Workers","cause":"Running on a Node version before 22 or an environment without Web Crypto API.","error":"Error: CryptoWeb is not supported in this environment"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/mhbdev/tele-better-auth#readme","github":"https://github.com/mhbdev/tele-better-auth","docs":null,"changelog":null,"pypi":null,"npm":"tele-better-auth","openapi_spec":null,"status_page":null,"smithery":null,"categories":["authentication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}