Installation

Zaileys is published to npm as a single package, zaileys. It ships dual ESM and CommonJS bundles with type declarations for both module systems, so it works the same whether you write TypeScript, ESM JavaScript, or CommonJS JavaScript.

Install the package

npm i zaileys

pnpm add zaileys

yarn add zaileys

bun add zaileys

That single install is everything you need for a working bot. The default file auth store is zero-config and needs nothing extra — every storage backend besides file and the native image accelerator are optional (see below).

Runtime requirements

Zaileys targets Node.js v20 or newer (engines.node >= 20.0.0). It is also verified to run on Bun, Deno, and Termux.

For per-runtime caveats (the node: protocol on Deno, ffmpeg fallback on Termux, etc.) see Runtime Support.

ESM-only project setup

In an ESM project (your package.json has "type": "module", or the file is .mjs / .ts compiled to ESM), import normally:

import { Client } from 'zaileys'
 
const client = new Client()

In a CommonJS project (no "type": "module", or a .cjs file), use require:

const { Client } = require('zaileys')
 
const client = new Client()

TypeScript setup

Zaileys ships its own type declarations (dist/index.d.ts), so there is nothing to install from @types. For the best experience use a modern module-resolution mode in your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

module: "NodeNext" (or "Node16" / "Bundler") lets TypeScript pick the right entry point from the package exports map automatically. strict is recommended — Zaileys is fully typed and the event payloads are richest under strict mode.

A common quick way to run a TypeScript bot during development without a separate build step:

npm i -D tsx
npx tsx bot.ts

pnpm add -D tsx
pnpm tsx bot.ts

yarn add -D tsx
yarn tsx bot.ts

# Bun runs TypeScript natively — no extra tooling
bun run bot.ts

Optional peer dependencies

Zaileys declares its storage drivers as optional peer dependencies. They are not installed by default, and a missing one never breaks npm install — Zaileys loads each driver lazily and only throws (STORE_NOT_AVAILABLE) if you actually construct an adapter whose driver is absent. Install only the ones you use.

npm i better-sqlite3   # SQLite adapters
npm i pg               # PostgreSQL adapters
npm i redis            # Redis adapters
npm i convex           # Convex adapters

pnpm add better-sqlite3   # SQLite adapters
pnpm add pg               # PostgreSQL adapters
pnpm add redis            # Redis adapters
pnpm add convex           # Convex adapters

yarn add better-sqlite3   # SQLite adapters
yarn add pg               # PostgreSQL adapters
yarn add redis            # Redis adapters
yarn add convex           # Convex adapters

bun add better-sqlite3   # SQLite adapters
bun add pg               # PostgreSQL adapters
bun add redis            # Redis adapters
bun add convex           # Convex adapters

better-sqlite3 is a native module that compiles on install. With pnpm you may need to allow its build script (pnpm approve-builds / the onlyBuiltDependencies allowlist). See Storage Adapters for how to wire each backend into the client.

Native image acceleration — sharp

sharp is an optional accelerator for image and sticker processing. It is not a declared dependency: Zaileys loads it opportunistically (in both ESM and CJS) and falls back to the bundled pure-JS jimp path when it is absent, so everything works without it — just slower for heavy media workloads.

npm i sharp

pnpm add sharp

yarn add sharp

bun add sharp

Verify the install

After installing, confirm the package imports and constructs cleanly. By default the client connects on construction (autoConnect is true), so for a no-side-effects smoke test pass autoConnect: false and call connect() yourself when ready.

import { Client } from 'zaileys'
 
const client = new Client({ autoConnect: false })
 
console.log('zaileys loaded:', typeof Client === 'function')
console.log('client constructed:', client instanceof Client)
 
// When you are ready to go online, start the connection explicitly:
// await client.connect()
// client.on('qr', ({ qrString }) => console.log(qrString))

npx tsx verify.ts