WyzBooks WyzBooks v26.4.140658

Developer

This topic covers running WyzBooks from source during development. For built-app usage, see the Command Line topic.

Running from Source

Clone the repository and install dependencies, then launch the Electron app:

npm install
npm start                # Launch the app
npm run dev              # Launch in development mode

CLI arguments are passed after a double dash:

npm start -- <arguments>

CLI Arguments

All arguments documented in Command Line work identically from source. Here are the npm equivalents:

Data Reset
# Full factory reset — data and settings
npm start -- --reset

# Reset data only, keep settings
npm start -- --reset-data

# Reset settings only, keep data
npm start -- --reset-prefs

# Reset data then import
npm start -- --reset-data --iif ~/Downloads/company.iif
Importing Data
# Import an IIF file
npm start -- --iif ~/Downloads/company-backup.iif

# Import a CSV transaction file
npm start -- --csv ~/Accounting/2025-transactions.csv

# Full pipeline: IIF + CSV + enrichment
npm start -- --iif ~/Downloads/chart.iif --csv ~/Downloads/txns.csv --csvb ~/Downloads/detail.csv

# Fresh start: reset everything, then full import
npm start -- --reset --iif ~/QB-Export/accounts.iif --csv ~/QB-Export/transactions.csv --csvb ~/QB-Export/invoice-detail.csv
Debugging
# Inspect a specific invoice after import
npm start -- --iif data.iif --csv txns.csv --dump-invoice 1042

# Check a different invoice
npm start -- --dump-invoice 2001

# Dump all A/R balances
npm start -- --reset --iif data.iif --csv txns.csv --dump-ar

# Combine both
npm start -- --csv ~/Downloads/transactions.csv --dump-invoice 1001 --dump-ar
Report Comparison (Headless)
# Compare trial balance
npm start -- --compare trial ~/Downloads/qb-trial-balance.csv

# Compare with date range
npm start -- --compare trial ~/Downloads/qb-trial.csv --date-from 2025-01-01 --date-to 2025-03-31

# Compare P&L for fiscal year
npm start -- --compare pnl ~/Accounting/qb-pnl-2025.csv --date-from 2025-01-01 --date-to 2025-12-31

# Compare A/R Aging (no date range needed)
npm start -- --compare ar_aging ~/Downloads/qb-ar-aging.csv

npm Commands

  • npm start — Launch the Electron app.
  • npm run dev — Launch in development mode.
  • npm run build — Build macOS universal binary via electron-builder (dir target) and run postbuild.
  • npm run build:dmg — Build macOS universal DMG installer and run postbuild.
  • npm run install:app — Copy built app to /Applications/WyzBooks.app.
  • npm run api — Start the REST API server on 127.0.0.1:3141 without launching the Electron app.
  • npm run test — Run the CPA-level accounting test suite (365 tests, 35 categories).
  • npm run test:lib — Run accounting module tests via the shared library (376 tests).
  • npm run test:api — Run REST API test suite (587 tests, 28 suites).
  • npm run test:ui — Run Playwright UI smoke tests (14 tests).
  • npm run vendor:update — Download fresh vendor libraries from CDN into src/vendor/ and run tests.

Testing

WyzBooks has seven test suites totaling 1,579 tests. See Accounting Tests for details.

# Run all suites
npm run test && npm run test:lib && npm run test:api && npm run test:ui && node tests/shared-file.test.js && node tests/lib/event-store.test.js && node tests/lib/projection.test.js

# Run just the CPA accounting tests
npm run test

# Run just the API tests
npm run test:api

# Run UI smoke tests
npm run test:ui

# Run multi-user shared file tests
node tests/shared-file.test.js

Building

# Build universal binary (dir target)
npm run build

# Build DMG installer
npm run build:dmg

# Build and install to /Applications
npm run build && npm run install:app

The build produces a macOS universal binary (x86_64 + ARM64). The postbuild script registers the app with macOS Launch Services.

Documentation Site

  • npm run docs:demo — Generate demo data at /tmp/wyzbooks-docs-demo/.
  • npm run docs:screenshots — Capture app screenshots with demo data via Playwright.
  • npm run docs:build — Build docs site (local, pathPrefix /).
  • npm run docs:full — Full pipeline: demo data → screenshots → build.
  • npm run docs:deploy — Build docs site and rsync to Apache server.
  • npm run deploy:site — Rsync product website (html/) to wyzbooks.com.

White Screen Debugging

If the app shows a blank white screen, it usually means a JSX/JavaScript error. To see the exact error with line numbers, temporarily add this to main.js after the loadFile() call:

mainWindow.webContents.on("console-message", (e, level, msg, line, src) => {
  console.log(`[renderer] ${msg} (${src}:${line})`);
});
Tip
  • Babel Standalone shows the exact line and column of the error. Remove this listener after debugging.
  • Common causes: mismatched React.createElement parentheses, missing props in top-level components, hooks called out of order.

Vendor Libraries

WyzBooks runs fully offline. All UI dependencies are bundled in src/vendor/. To update them from CDN:

npm run vendor:update

This downloads React 18, ReactDOM 18, Babel Standalone, Tailwind CSS 2.2.19, and Swagger UI 5, then runs the test suite to verify nothing broke.

For related topics, see Command Line for built-app CLI usage, REST API for the HTTP API, and Accounting Tests for the test suite.

← Command Line INI Options →