Registry / communication / tdl
library6.0.0jsnpmunverified

tdl is a JavaScript wrapper for TDLib (Telegram Database Library), providing Node.js bindings to create custom Telegram clients or bots. Currently at version 8.1.0, it is actively maintained with releases often following new TDLib versions. A key differentiator is its direct, low-level integration with the native TDLib, allowing full control over Telegram API interactions, unlike higher-level bot libraries. It requires a separate installation or build of the `tdjson` shared library from TDLib itself. tdl ships with TypeScript type definitions, enabling robust development in modern JavaScript environments.

npm install tdl
INSTALL
IMPORT
SIG · TDL
T
tdl
communicationjavascriptv6.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient
✓ import { createClient } from 'tdl'
✗ const tdl = require('tdl'); tdl.createClient(...)
While `require('tdl')` in CJS returns an object where `createClient` is a property, the recommended ESM import is a named import for `createClient` directly.
configure
✓ import { configure } from 'tdl'
✗ const tdl = require('tdl'); tdl.configure(...)
Used to specify the path to the `tdjson` shared library or configure other global settings. For ESM, it's a named import.
getTdjson
✓ import { getTdjson } from 'prebuilt-tdlib'
✗ const { getTdjson } = require('tdl')
This function is provided by the separate `prebuilt-tdlib` package, not `tdl`, and is used to dynamically locate the pre-built `tdjson` shared library.
Client (type)
✓ import type { Client } from 'tdl'
Imports the TypeScript type definition for the `Client` instance returned by `createClient`.

Demonstrates initializing `tdl` with `prebuilt-tdlib`, creating a client, handling errors, and observing authorization state changes during login.

import { createClient, configure } from 'tdl'; import { getTdjson } from 'prebuilt-tdlib'; // IMPORTANT: Configure tdl to use the pre-built tdjson library. // This must be done BEFORE creating any client instances. configure({ tdjson: getTdjson() }); // Replace with your actual API ID and Hash from https://my.telegram.org/ const apiId = Number(process.env.TELEGRAM_API_ID ?? 12345); const apiHash = process.env.TELEGRAM_API_HASH ?? '0123456789abcdef0123456789abcdef'; const client = createClient({ apiId: apiId, apiHash: apiHash }); client.on('error', (error) => { console.error('tdl client error:', error); }); client.on('update', (update) => { // console.log('Received update:', update); if (update._ === 'updateAuthorizationState') { if (update.authorization_state._ === 'authorizationStateWaitPhoneNumber') { console.log('Please enter your phone number (e.g., +12345678900):'); // In a real app, you would prompt the user for input here // For demonstration, we'll exit after waiting. setTimeout(() => client.destroy(), 5000); } else if (update.authorization_state._ === 'authorizationStateReady') { console.log('Client is ready!'); client.destroy(); // Destroy client for quickstart, in real app keep running } } }); console.log('Connecting to Telegram...'); client.login(() => console.log('Login initiated.'));
Debug
Known issues
breakingtdl requires the `tdjson` shared library of TDLib (Telegram Database Library) to be present on the system. This is a separate dependency not bundled with the `tdl` npm package.
fix
Install `prebuilt-tdlib` (`npm install prebuilt-tdlib`) and configure tdl using `configure({ tdjson: getTdjson() })` or manually provide the path to `libtdjson.so`/`.dylib`/`.dll` via `configure({ tdjson: '/path/to/libtdjson.so' })`.
affects: >=1.0.0
gotchaThe `tdjson` shared library must be TDLib version 1.8.0 or newer. Using an older version can lead to crashes or unexpected behavior due to API mismatches.
fix
Ensure `prebuilt-tdlib` installs a compatible TDLib version, or if building manually, use TDLib source version 1.8.0 or newer.
affects: >=1.0.0
gotchaIf pre-built Node.js addons for `tdl` are not available for your specific platform/architecture, `npm install` will attempt to build the addon from source using `node-gyp`. This requires a C++ compiler (C++14 capable), Python, and relevant build tools (e.g., MSVS on Windows) to be installed.
fix
Install necessary build tools for your operating system. For Windows, install 'Desktop development with C++' from Visual Studio Installer. For Linux, `build-essential` and Python. For macOS, Xcode Command Line Tools.
affects: >=1.0.0
gotchaValid Telegram API ID and API Hash are mandatory for `tdl.createClient()`. Using incorrect or placeholder values will result in authentication failures.
fix
Obtain your `apiId` and `apiHash` by logging in at `https://my.telegram.org/` under 'API development tools'.
affects: >=1.0.0
breakingtdl requires Node.js v16 or newer. Older Node.js versions are not supported and may lead to installation failures or runtime errors.
fix
Upgrade your Node.js environment to version 16.14.0 or higher.
affects: <8.0.0
Errors
Common errors & fixes
Error: Cannot find tdjson library
The `tdjson` shared library (`libtdjson.so`, `libtdjson.dylib`, or `tdjson.dll`) was not found in expected system paths or via configuration.
fix
Ensure `prebuilt-tdlib` is installed and `tdl.configure({ tdjson: getTdjson() })` is called before `createClient()`, or provide a direct path via `tdl.configure({ tdjson: '/path/to/libtdjson.so' })`.
node-gyp rebuild error
The `tdl` Node.js addon failed to compile from source due to missing C++ compilers, Python, or other build dependencies.
fix
Install a C++ compiler (e.g., `build-essential` on Linux, Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows) and Python.
updateAuthorizationState: authorizationStateWaitTdlibParameters
The client was initialized with incorrect `apiId` or `apiHash` values, preventing proper authorization with Telegram.
fix
Verify your `apiId` and `apiHash` are correct and obtained from `https://my.telegram.org/`.
TypeError: Cannot read properties of undefined (reading 'createClient') or TypeError: tdl.createClient is not a function
Incorrect import statement or attempting to use `tdl.createClient` in a CommonJS context where `tdl` might not be the expected object.
fix
For ESM, use `import { createClient } from 'tdl'`. For CommonJS, use `const { createClient } = require('tdl')` if not using `tdl.configure()` first, or `const tdl = require('tdl')` and then `tdl.createClient()` after `tdl.configure()`.
Upgrade
Version history
6.0.0latest on npm
Audit
Dependencies
prebuilt-tdliboptionalProvides the `tdjson` shared library required by tdl. While optional if you build TDLib manually, it is the recommended and most convenient way to acquire the native library.
Agent activity
36 hits · last 30 days
node
34
OpenAI (training)
1
Resources