A local-first Excel BOQ diff tool for construction cost engineers and quantity surveyors.
Trace every change between two bills of quantities without uploading the files.
Important
v0.1.0 is the first public release. The live demo is deployed from main through GitHub Pages. Imported BOQ files stay in the current browser session and are never uploaded.
Revised tender BOQs are often checked with VLOOKUP, XLOOKUP, conditional formatting, and manual row-by-row review. Inserted rows, duplicate or missing item codes, renamed codes, and different column layouts make those comparisons fragile. BOQ Diff independently maps both sheets, applies deterministic and explainable matching, highlights field-level changes, and exports a traceable Excel review report.
Typical uses include tender addenda, bid pricing revisions, maximum bid price reviews, and submitted-versus-approved settlement checks. See the detailed industry workflow.
- Import two
.xlsxor.csvfiles locally, select one sheet from each, and map fields independently. - Detect likely header rows and common Chinese column names, then preview effective rows.
- Preserve excluded blank, section, subtotal, total, and explanatory rows with source row numbers and reasons.
- Match unique codes, disambiguate duplicates, find exact feature matches, and propose fuzzy candidates.
- Require human review for medium-confidence or ambiguous candidates and support undo.
- Compare code, name, description, unit, quantity, unit price, and total price with configurable tolerances.
- Summarize additions, removals, changes, unchanged rows, pending rows, and confirmed net amount impact.
- Filter a virtualized result list, inspect field-level details, and export a formatted multi-sheet Excel report.
- Load deterministic, entirely fictional demo data.
- Open the live demo or local app, then import baseline and target files or load the demo data.
- Select the sheets, verify both field mappings and previews, run the comparison, and resolve pending matches.
- Review the summary and field changes, filter as needed, then export the Excel review report.
The default limit is 25 MB per file and 30,000 effective rows per sheet. Oversized input is rejected with an explanation rather than silently truncated.
Parsing, matching, diffing, and report generation run in the browser. Workbook contents, BOQ rows, filename history, project amounts, and exports are not persisted. Refreshing or choosing “Clear data” releases the session data. Only the theme, non-sensitive mapping preferences, and comparison tolerances may be stored in localStorage. The app has no backend, account system, telemetry, advertising, external API, or file-upload endpoint.
Read the privacy and security model before handling sensitive project information. Your organization's information-security rules still apply.
Matching is deterministic and explainable. It proceeds through unique normalized codes, duplicate-code disambiguation using name/description/unit, exact feature matches for missing or changed codes, and blocked fuzzy candidates. Quantity and price are change fields, not primary identity signals. The default automatic threshold is 0.88; scores from 0.72 to 0.88 and near-tied candidates require confirmation. See matching rules for weights, exclusions, amount calculations, and limitations.
| Format | Support | Notes |
|---|---|---|
.xlsx |
Import and report export | Cached formula results are used only when safely available; formulas are not recalculated |
.csv |
Import | Treated as one sheet |
.xls |
Not supported | Save as .xlsx with Excel or WPS first |
| Proprietary GBQ/GTJ files | Not supported | No proprietary construction-file parser |
| PDF or scans | Not supported | v0.1.0 includes no OCR |
Use Node.js 24 LTS and npm. package-lock.json is authoritative.
git clone https://github.com/KanadeK/boq-diff.git
cd boq-diff
npm ci
npm run devImportant commands are npm run dev, npm run build, npm run preview, npm run lint, npm run format, npm run format:check, npm run typecheck, npm run test, npm run test:unit, npm run test:e2e, npm run verify, and npm run generate:fixtures.
The Vite base is /boq-diff/. A push to main triggers the official GitHub Pages workflow, which installs with npm ci, verifies and builds, uploads dist, and deploys through GitHub's official Pages Actions. The repository owner must first select GitHub Actions under Settings > Pages > Build and deployment > Source. Nothing in this local project creates a repository, pushes commits, publishes Pages, or creates a release automatically. Follow PUBLISHING.md for the preflight and manual steps.
v0.1.0 compares two BOQ worksheets only. It does not provide AI, accounts, a backend, a database, OCR, PDF or proprietary-file parsing, automated pricing, market quotations, collaborative project management, missing-item detection, or compliance decisions. It never edits the imported source files directly.
BOQ Diff is a mechanical difference-identification and review aid. Its matches, amount impacts, and reports do not replace the professional judgment of a registered cost engineer, quantity surveyor, or project cost professional. Always verify conclusions against the source workbooks, contract documents, and applicable rules.
Terminology and business context refer to China's Standard for Bill of Quantities and Valuation for Construction Works, GB/T 50500-2024. The project neither reproduces the standard nor claims official certification, authorization, or automatic compliance.
The roadmap keeps multi-sheet batches, mapping templates, CostLint checks, cross-project comparisons, local history, Tauri, and very large workbook optimization out of v0.1.0.
All built-in demos and generated fixtures are entirely fictional and contain no real project, company, proprietary software template, or copyrighted pricing database. Do not attach real project data to issues.
Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately under SECURITY.md.
Copyright (c) 2026 KanadeK. Licensed under the MIT License.