Configuration
Relevant source files
The following files were used as context for generating this wiki page:Configuration in the whatsapp-chat-analytics project is divided into two main areas: the backend decryption tool (chatsExporter) and the frontend web application (web). The backend relies on environment variables and in-script constants to manage the decryption process of WhatsApp database files. The frontend uses a combination of Webpack overrides, package.json scripts, and application-level constants to manage its build process, dependencies, and user interface behavior.
This document details the configuration options available for both parts of the project, explaining how they are used and their impact on the application's functionality. All settings are managed locally on the user's machine, ensuring that sensitive data like encryption keys never leave the device.
Backend Configuration (chatsExporter)
The backend configuration is centered around the whatsapp_db_android_exporter.py script. It uses a .env file for sensitive data and has several hardcoded constants for controlling its behavior.
Sources: chatsExporter/whatsapp_db_android_exporter.py, README.md
Environment Variables
The script loads configuration from a .env file located in the chatsExporter directory. A .env.example file is provided as a template.
Sources: README.md:30-31, chatsExporter/whatsapp_db_android_exporter.py:83-88
| Variable | Description | Example |
|---|---|---|
ENCRYPTION_KEY | The 64-character hexadecimal key for decrypting WhatsApp backups. | a1b2c3... |
TARGET_DIR | The directory path containing the .crypt15 backup files. Defaults to the current directory if not set. | ./backups |
Sources: README.md:33-36, chatsExporter/whatsapp_db_android_exporter.py:84-88
In-Script Configuration
The Python script itself contains configurable constants at the top of the file that control its execution logic.
Sources: chatsExporter/whatsapp_db_android_exporter.py:19-23
| Constant | Type | Default Value | Description |
|---|---|---|---|
KEYFILE_PATH | str or None | None | Path to a pre-existing .key file. If set, the script skips key creation from the hex ENCRYPTION_KEY. |
FORCE_INSTALL | bool | False | If True, forces the re-installation of the wa-crypt-tools dependency. |
DEFAULT_KEY_FILENAME | str | "encrypted_backup.key" | The default filename the script expects wacreatekey to produce. |
Sources: chatsExporter/whatsapp_db_android_exporter.py:19-23
Decryption Configuration Flow
The following diagram illustrates how the configuration variables are used within the whatsapp_db_android_exporter.py script to perform decryption.
This diagram shows the logical flow of the decryption script, starting from loading environment variables to the final output of decrypted database files.
Sources: chatsExporter/whatsapp_db_android_exporter.py
Frontend Configuration (web)
The frontend configuration manages the React application's build process, dependencies, and in-app constants.
Webpack Overrides
The project uses react-app-rewired to customize the underlying Webpack configuration of Create React App without ejecting. The configuration is defined in web/config-overrides.js. This is primarily used to provide browser-compatible polyfills for Node.js core modules that are dependencies of other packages (like sql.js).
Sources: web/config-overrides.js, web/package.json:26
The following diagram shows how react-app-rewired injects custom configuration.
This diagram illustrates the build process override mechanism.
Sources: web/config-overrides.js, web/package.json:26
The main configurations are:
- Resolve Fallbacks: Provides browser implementations for Node.js modules.
- ProvidePlugin: Automatically loads modules (
process,Buffer) as needed instead of requiringimport.
| Node.js Module | Polyfill | Purpose |
|---|---|---|
crypto | crypto-browserify | Provides cryptographic functionality in the browser. |
vm | vm-browserify | Emulates Node's vm module for running code in a sandbox. |
stream | stream-browserify | Provides a browser version of Node's stream API. |
path | path-browserify | Provides a browser version of Node's path utility. |
fs | false | Explicitly disabled as it has no browser equivalent. |
Sources: web/config-overrides.js:4-10
Package Scripts
The web/package.json file defines the scripts for running, building, and testing the web application. These scripts use react-app-rewired instead of the standard react-scripts.
| Script | Command | Description |
|---|---|---|
start | cross-env DISABLE_ESLINT_PLUGIN=true react-app-rewired start | Starts the development server with ESLint plugin disabled. |
build | react-app-rewired build | Builds the app for production. |
test | react-app-rewired test | Runs tests. |
eject | react-app-rewired eject | Ejects from Create React App (using the rewired version). |
Sources: web/package.json:25-30
Web App Manifest
The web/public/manifest.json file provides metadata for the Progressive Web App (PWA). This configuration controls how the app appears when installed on a user's mobile device or desktop.
| Property | Value | Description |
|---|---|---|
short_name | "WhatsApp Chats Analysis" | The name shown on the user's home screen. |
name | "WhatsApp Chats Analysis" | The full name of the application. |
start_url | "." | The entry point of the application. |
display | "standalone" | Opens the app in its own window, without browser UI. |
theme_color | "#000000" | The color of the toolbar. |
background_color | "#ffffff" | The color of the splash screen background. |
Sources: web/public/manifest.json:2-8
Application Constants
The application uses constant files to manage static data and configuration used within the React components, such as UI labels and mappings for database values.
For example, web/src/Pages/SearchSQLite/constants.js defines data structures for UI components like filter pickers.
// web/src/Pages/SearchSQLite/constants.js:2-12
export const MEDIA_TYPE_DATA = [
{ label: 'Text', value: 'text' },
{ label: 'Image', value: 'image' },
{ label: 'Audio', value: 'audio' },
{ label: 'Document', value: 'document' },
{ label: 'Video', value: 'video' },
{ label: 'Sticker', value: 'sticker' },
{ label: 'Location', value: 'location' },
{ label: 'Contact', value: 'contact' },
{ label: 'Poll', value: 'poll' },
];
This array is used to populate the "Msg type" filter in the search interface.
Sources: web/src/Pages/SearchSQLite/constants.js:2-12, web/src/Pages/SearchSQLite/components/SearchStep.jsx:49