Standalone Web App — Get Started with OpenTax

Quickstart

Get a local instance running in three commands. You'll need Node.js 20+ installed.

Clone & install


          $ git clone https://github.com/xavierliwei/opentax.git

          $ cd opentax

          $ npm install

Start the dev server


          $ npm run dev

          

          # Opens at http://localhost:5173

That's it. Open http://localhost:5173 in your browser and you're running a full tax preparation environment.

What you get

The standalone app bundles everything a tax filer needs into a single client-side application.

Document import

Upload W-2s, 1099s, and broker statements. OCR runs locally via Tesseract.js—no server upload.

Guided interview

13-step interview walks through income, deductions, credits, and dependents with real-time computation.

Full traceability

Click any computed line to see exactly how it was derived, which IRS rule applies, and which documents contributed.

PDF generation

Download IRS-ready Form 1040, schedules, and supporting forms for e-filing via IRS Free File or mailing.

Zero data transmission

Everything runs in the browser. Tax data is stored in IndexedDB locally. No server calls, no accounts, no tracking.

State returns

42 states supported: AL, AR, AZ, CA, CO, CT, DC, DE, GA, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MS, MT, NC, ND, NE, NJ, NM, NY, OH, OK, OR, PA, RI, SC, UT, VA, VT, WI, and WV. Federal + state computed together.

Tech stack

Modern frontend tools, zero backend dependencies for the standalone mode.

Layer	Technology	Purpose
Framework	React 19 + React Router 7	UI rendering and client-side routing
State	Zustand 5	Tax return state with IndexedDB persistence
Styling	Tailwind CSS 4	Utility-first CSS with native `@theme` config
Build	Vite 6	Dev server with HMR, production bundling
OCR	Tesseract.js 5	Client-side document text extraction
PDF	pdf-lib	Client-side IRS form filling and download
Testing	Vitest 3	Unit and integration tests (2,300+ test cases)

Project structure

Key directories and what they contain.

Project layout

opentax/
├── src/
│   ├── rules/
│   │   └── 2025/          # IRS rules engine (TY2025)
│   │       ├── form1040.ts    # Form 1040 computation
│   │       ├── scheduleA.ts   # Itemized deductions
│   │       ├── scheduleD.ts   # Capital gains
│   │       ├── ...            # All supported federal forms
│   │       └── al/ az/ ca/ co/ ct/ dc/ ga/ ia/ id/ il/ in/ ks/ ky/ la/ ma/ md/ mi/ mn/ mo/ ms/ nc/ nj/ ny/ oh/ ok/ or/ pa/ sc/ ut/ va/ wi/ # State returns
│   ├── ui/
│   │   ├── components/    # React components
│   │   ├── pages/         # Route pages (interview steps)
│   │   └── store/         # Zustand state management
│   ├── services/
│   │   └── TaxService.ts     # Public API for the engine
│   └── trace/             # Explainability / trace tree
├── server/                # Express backend (plugin mode)
├── openclaw-plugin/       # OpenClaw agent tool defs
├── docs/                  # GitHub Pages site (you are here)
└── tests/                 # 2,300+ test cases

Development workflow

Common commands for day-to-day development.

Run tests


            $ npm test              # Run full test suite

            $ npm test -- --watch   # Watch mode for TDD

Production build


            $ npm run build         # Build to dist/

            $ npm run preview       # Preview production build

Lint and type-check


            $ npx tsc --noEmit      # TypeScript type checking

            $ npm run lint           # ESLint