Runtime Support

Zaileys ships dual ESM and CommonJS entry points (dist/index.mjs + dist/index.cjs) with matching type declarations (dist/index.d.ts + dist/index.d.cts). The same package runs on Node.js, Bun, Deno, and Termux (Android) — both import and require('zaileys') resolve correctly through the exports map.

import { Client } from 'zaileys'           // ESM / TypeScript

const { Client } = require('zaileys')       // CommonJS

Compatibility matrix

ESM vs CommonJS

The package is "type": "module" with a fully specified exports field:

{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

That means both styles are first-class — pick whichever matches your project:

import { Client } from 'zaileys'
 
const client = new Client({
  authType: 'pairing',
  phoneNumber: 628000000000,
})
 
client.on('connection', ({ status }) => console.log(status))
await client.connect()

const { Client } = require('zaileys')
 
const client = new Client({
  authType: 'pairing',
  phoneNumber: 628000000000,
})
 
client.on('connection', ({ status }) => console.log(status))
client.connect()

Node.js

Node.js is the primary target. Any release >=20.0.0 works; LTS (20/22/24) is recommended.

npm install zaileys

pnpm add zaileys

yarn add zaileys

# Compile then run
node dist/bot.js
 
# Or run TypeScript directly with tsx (no build step)
npx tsx bot.ts

Bun

Bun runs both the ESM and CJS bundles directly and executes TypeScript natively, so there is no separate build step.

bun add zaileys

# Bun runs .ts files directly
bun run bot.ts

import { Client } from 'zaileys'
 
const client = new Client({ authType: 'qr' })
await client.connect()

Deno

Deno can run Zaileys through the npm: specifier or from a local node_modules directory. Because the bundle uses the node: protocol for every built-in, no shimming is required — but npm dependencies must be materialized to disk.

deno cache --node-modules-dir npm:zaileys

deno run --node-modules-dir --allow-all bot.ts

import { Client } from 'npm:zaileys'
 
const client = new Client({ authType: 'qr' })
await client.connect()

Termux (Android)

Termux installs Zaileys as a normal Node project. The recommended install skips the native sharp accelerator — Baileys declares sharp as a peer dependency, so a plain npm install tries to compile it from source and fails on Android (no prebuilt ARM binary, missing libvips/node-addon-api). Zaileys never needs sharp: image processing falls back to the bundled pure-JS jimp path automatically.

pkg update && pkg upgrade
pkg install nodejs-lts ffmpeg

npm install zaileys --legacy-peer-deps

npx tsx bot.ts
# or: node dist/bot.js

Native dependencies per runtime

Zaileys keeps heavy native modules optional. They are declared as optional peer dependencies and loaded lazily, so the core library installs and runs without any compiler.

sharp (image acceleration)

sharp is not a declared dependency of Zaileys. Zaileys probes for it at runtime using a hybrid loader (require('sharp') first, then dynamic import('sharp')), so it works in both ESM and CJS bundles. If sharp is absent or fails to load, image and sticker processing automatically fall back to the bundled pure-JS jimp path. Install it only when you want the faster native path:

npm i sharp

better-sqlite3 and other storage adapters

Storage adapters are wired through optional peer dependencies. Install only the driver for the backend you actually use:

npm i better-sqlite3   # SQLite
npm i pg               # Postgres
npm i redis            # Redis

pnpm add better-sqlite3
pnpm add pg
pnpm add redis

yarn add better-sqlite3
yarn add pg
yarn add redis

bun add better-sqlite3
bun add pg
bun add redis

Quick reference

• Node.js — >=20.0.0; the primary, fully supported runtime.
• Bun — bun add zaileys, runs .ts directly; ignore harmless ws upgrade warnings.
• Deno — import 'npm:zaileys', always run with --node-modules-dir plus the right permissions.
• Termux — install with npm install zaileys --legacy-peer-deps (skips Baileys’ native sharp peer that fails to compile on Android); pkg install nodejs-lts ffmpeg; prefer file/memory storage and the jimp fallback.

For platform-agnostic install steps see Installation, for picking a session backend see Storage Adapters, and for runtime-specific failures see Troubleshooting.