Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
telegram
✓ import { telegram } from 'tele-better-auth'
✗ const telegram = require('tele-better-auth')
ESM-only; CommonJS require will fail due to 'type': 'module' in package.json
telegramClient
✓ import { telegramClient } from 'tele-better-auth/client'
✗ import { telegramClient } from 'tele-better-auth'
Client-side helper is exported from the /client subpath, not the main entry
userHasTelegramLinked
✓ import { userHasTelegramLinked } from 'tele-better-auth/server'
✗ import { userHasTelegramLinked } from 'tele-better-auth'
Server utility is exported from the /server subpath; added in v1.1.0
Sets up the Telegram plugin on the server, creates an auth client with the client plugin, and demonstrates sign-in via the login widget.
import { betterAuth } from 'better-auth';
import { telegram } from 'tele-better-auth';
export const auth = betterAuth({
plugins: [
telegram({
botToken: process.env.TELEGRAM_BOT_TOKEN ?? '',
botUsername: 'my_bot',
}),
],
});
// Client side:
import { createAuthClient } from 'better-auth/client';
import { telegramClient } from 'tele-better-auth/client';
export const authClient = createAuthClient({
plugins: [telegramClient()],
});
// Sign in widget:
authClient.initTelegramWidget(
'telegram-login-container',
{ size: 'large', cornerRadius: 20 },
async (authData) => {
const result = await authClient.signInWithTelegram(authData);
if (!result.error) window.location.href = '/dashboard';
},
);
Debug
Known issues
breakingRequires better-auth ^1.6.11; incompatible with older versions.fixUpdate better-auth to >=1.6.11
affects: <1.6.11 for better-auth
breakingRequires Node.js >=22 or runtime with full Web Crypto API; older Node versions (e.g., 16, 18, 20) will fail.fixUpgrade Node.js to >=22 or use a runtime like Bun, Deno, or Cloudflare Workers
affects: <1.0.0 for Node
gotchaClient-side plugin must be imported from 'tele-better-auth/client', not 'tele-better-auth'.fixUse import { telegramClient } from 'tele-better-auth/client' affects: >=1.0.0
gotchaThe bot token must be kept secret; exposing it allows anyone to impersonate your bot and sign in as arbitrary users.fixStore TELEGRAM_BOT_TOKEN in environment variables; never bundle it in client code
affects: >=1.0.0
deprecatedThe old 'initTelegramLogin' and 'openTelegramLogin' helpers (pre v1.3) have been deprecated in favor of 'initTelegramWidget' and 'renderTelegramLoginButton'.fixUse the newer widget/button API methods (see README)
affects: >=1.3.0
Errors
Common errors & fixes
Error: Package 'tele-better-auth' is not compatible with this version of better-auth.
Incompatible better-auth version (e.g., <1.6.11) or wrong peer dependency.
fixUpdate better-auth to ^1.6.11: npm install better-auth@^1.6.11
TypeError: Cannot read properties of undefined (reading 'initTelegramWidget')
Forgot to add telegramClient() plugin to the client or imported from wrong path.
fixEnsure you call telegramClient() in createAuthClient plugins: import { telegramClient } from 'tele-better-auth/client' and add it. Error: CryptoWeb is not supported in this environment
Running on a Node version before 22 or an environment without Web Crypto API.
fixUpgrade to Node >=22 or use Bun/Deno/Cloudflare Workers
Audit
Dependencies
better-authrequiredPeer dependency; the plugin requires Better Auth core to function