Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wppconnect-team/wa-js/llms.txt

Use this file to discover all available pages before exploring further.

WA-JS can be built and tested locally against any WhatsApp Web version listed in the @wppconnect/wa-version package. This is the primary workflow for adding new features, fixing bindings that break after a WhatsApp update, and verifying that patches work across multiple WA versions before shipping a release.

​
Prerequisites

  • Node.js 24 — the repository pins this version in .nvmrc. Use nvm install to switch to it automatically if you have nvm installed.
  • npm — bundled with Node.js.
Clone the repository and install dependencies: 
git clone https://github.com/wppconnect-team/wa-js.git
cd wa-js
npm install

​
Build commands

WA-JS is bundled by Webpack into a single UMD file at dist/wppconnect-wa.js. Three build modes are available: 
# Production build — minified, no source maps
npm run build:prd

# Development build — inline source maps for DevTools debugging
npm run build:dev

# Watch mode — rebuilds automatically on file save
npm run watch
Use build:dev while iterating on a fix. Source maps make stack traces readable in the browser’s DevTools. Switch to build:prd before opening a pull request or testing final behaviour.

​
Launching a local browser session

After building, inject the local bundle into a real WhatsApp Web tab: 
npm run launch:local
This opens a Chromium window pointed at https://web.whatsapp.com/ and injects dist/wppconnect-wa.js automatically on every page load. The browser caches WhatsApp’s source bundles inside the wa-source/ directory for later inspection.

​
Targeting a specific WhatsApp Web version

Pass the WA_VERSION environment variable to load a particular version: 
WA_VERSION="2.3000.1029560485" npm run launch:local
Available versions (including alpha builds) are listed in node_modules/@wppconnect/wa-version/html/. Use this env var whenever you need to verify that a fix works on an older version or to reproduce a regression reported against a specific release.

​
Downloading and inspecting WA source bundles

WA-JS reads WhatsApp’s internal module names and function signatures from the source bundles distributed by WhatsApp. The wa-source:populate script downloads and caches these bundles locally: 
# Download the latest 20 versions (default)
npm run wa-source:populate

# Download all available versions
npm run wa-source:populate -- --all

# Download a specific version
npm run wa-source:populate -- --version 2.3000.1029560485

# Re-download versions that are already cached
npm run wa-source:populate -- --force
The bundles are minified and difficult to read as-is. Format a specific version before inspecting it: 
npm run wa-source:format 2.3000.1029560485
This runs Prettier over the downloaded JS files and makes identifiers, function signatures, and module boundaries readable in any text editor or IDE.

​
Comparing WhatsApp Web versions

When a binding breaks after a WA update, the quickest way to find what changed is to diff the two versions side by side: 
# Overview of module differences between two versions
./scripts/compare-wa-versions.sh 2.3000.1031980585 2.3000.1031992593

# Diff a specific module between versions
./scripts/compare-wa-versions.sh 2.3000.1031980585 2.3000.1031992593 WAWebUpdateUnreadChatAction

# List all locally available versions
./scripts/compare-wa-versions.sh
Both versions must have been downloaded with wa-source:populate and formatted with wa-source:format before the script can compare them. The script shows modules that exist only in the older version, modules that are new in the newer version, and a diff of a specific module when one is named.

​
Running tests

WA-JS ships a Playwright test suite under tests/. Smoke tests run unauthenticated and catch the most common breakage — a WhatsApp update renames or removes a module that WA-JS patches: 
# Full test project (includes smoke tests)
npm test

# Smoke tests only
npm test -- tests/smoke.spec.ts
Tests that require an authenticated WhatsApp session use the loggedPage fixture. Bootstrap the session once by running: 
npm run test:prepare
This opens a visible browser window where you can scan the QR code. The session is then cached under your OS temp directory (wa-js-test-<browser>) and reused by all subsequent npm test runs without requiring another scan.

​
Linting

The project uses ESLint with strict TypeScript rules, Prettier formatting, and enforced import ordering: 
npm run lint
Run this before committing. A pre-commit hook via lint-staged also runs ESLint automatically on staged .ts files, but running it explicitly first gives you the full output in one go.

​
Debugging a broken binding

When a WPP.* function stops working after a WhatsApp Web update, the root cause is almost always one of three things:
  • The function was moved to a different internal module.
  • The function was renamed.
  • Arguments changed from positional to named parameters, or vice versa.
1

Identify the target version

Find the WhatsApp Web version that introduced the regression. Check the @wppconnect/wa-version release notes or compare the versions that pass and fail in CI.
2

Download and format both versions

Download the bundles for the working version and the broken version, then format them both:
npm run wa-source:populate -- --version 2.3000.1031980585
npm run wa-source:populate -- --version 2.3000.1031992593

npm run wa-source:format 2.3000.1031980585
npm run wa-source:format 2.3000.1031992593
3

Compare the module

Use the compare script to diff the specific internal module that the broken WA-JS binding wraps:
./scripts/compare-wa-versions.sh 2.3000.1031980585 2.3000.1031992593 WAWebSendMsgAction
The diff shows exactly what changed between the two versions of that module.
4

Update the binding in src/whatsapp/

WA-JS low-level bindings live in src/whatsapp/. Find the file that imports the function that changed and update the module name, function name, or argument mapping to match the new WA version.
5

Test against both versions

Run build:dev and launch locally against both the old and new WA version to confirm the fix works on both:
npm run build:dev && WA_VERSION=2.3000.1031980585 npm run launch:local
npm run build:dev && WA_VERSION=2.3000.1031992593 npm run launch:local
6

Run the test suite

Run the full test suite to confirm no regressions were introduced:
npm test
Fixes must work across all WhatsApp Web versions still listed in node_modules/@wppconnect/wa-version/html/, not just the latest one. If a workaround is only needed for older versions, mark it with a TODO comment so it can be cleaned up once those versions are retired.

​
Generating API docs

TypeDoc generates the public API reference from TypeScript source: 
npm run docs:build
The output is written to the docs/ directory. Run this after adding or changing JSDoc comments on exported functions.

Build docs developers (and LLMs) love

Get started for freeTalk to us