Live: https://mikecoker.github.io/retirement-planner/
A client-side retirement planning tool built with React and TypeScript. All calculations run in the browser — no data is sent to any server.
- Multiple plans — create, rename, duplicate, and switch between plans; each plan stores its own inputs, Roth conversion schedule, and optimizer state
- Year-by-year projection from current age through life expectancy, covering traditional, Roth, taxable brokerage, and HSA balances
- Roth conversion optimizer — compares a bracket × until-age strategy grid plus a year-by-year scenario against lifetime tax, terminal portfolio, and bracket-smoothing goals
- Social Security estimator — enter SSA.gov estimates at 62/67/70; slider interpolates using the actual SSA piecewise reduction formula with COLA applied annually after claim age
- Tax analysis — 2026 federal brackets extrapolated forward by inflation, correct SS provisional income formula, IRMAA surcharges, 65+ standard deduction, optional flat or bracketed state tax
- Monte Carlo simulation — 1,000 full projection reruns with randomized return assumptions, showing success rate
- Married household modeling — separate spouse age, retirement age, wages, Social Security, and life expectancy inputs
- Expense modeling — Basic combined household monthly categories or Advanced itemized expense editor with recurring, loan, one-time, and custom-timing entries
- Account modeling — Basic combined balance/contribution fields or Advanced account editor for ownership, per-account returns, owner-specific contributions, and guaranteed income streams
- Export — JSON plan file or Excel spreadsheet with year-by-year projection data
Importable sample plans live in sample-data. They cover single and married scenarios, different Social Security options, basic and advanced account setups, baseline expenses, Roth conversions, QCDs, and reduced Social Security assumptions.
Detailed user documentation is drafted in docs/wiki so it can be reviewed in pull requests and then published to the GitHub Wiki.
Home— wiki landing page and suggested first workflowUser Guide— detailed walkthrough of plans, setup, results, optimizer, Monte Carlo, import, and exportModel Assumptions— tax, RMD, Social Security, return, and projection assumptions
| Tab | Category | Description |
|---|---|---|
| Accounts | Setup | Basic household totals or Advanced owner-specific accounts, contributions, salaries, and return assumptions |
| Expenses | Setup | Basic household spending categories or Advanced itemized expense editor |
| Balances | Results | Portfolio balance by account type over time |
| Income | Results | Income sources: SS, withdrawals, conversions |
| RMDs & Conversions | Results | Required minimum distributions and Roth conversion amounts |
| Tax Analysis | Results | Marginal/effective tax rates and dollar amounts |
| Cash Flow | Results | Net cash flow year by year |
| Roth Optimizer | Tool | Strategy comparison and modeled conversion schedules |
| Monte Carlo | Tool | Success rate simulation |
- React 19 + TypeScript
- Vite
- Chart.js + react-chartjs-2
- Vitest (tests)
npm install
npm run devOpen http://localhost:5173.
To test from another device on the same Wi-Fi network, run:
npm run dev:lanOpen one of the printed Network URLs on the other device. Pass a different fixed port with npm run dev:lan -- --port 5174.
npm run dev # start local-only dev server
npm run dev:lan # start dev server and print same-network URLs for phone/tablet testing
npm run build # type-check + Vite bundle → dist/
npm run preview # serve the dist/ build locally
npm test # run unit testsPushing to main automatically deploys to GitHub Pages via .github/workflows/deploy.yml. The workflow builds with VITE_BASE_PATH=/retirement-planner/ and deploys dist/ using the GitHub Pages API.
To enable on a new repo: Settings → Pages → Source → GitHub Actions.
src/
financial.ts Core projection engine, tax calculations, SS interpolation
optimizer.ts Roth conversion strategy optimizer
exportSpreadsheet.ts Excel export
types.ts InputParams, ProjectionRow, Account, ExpenseItem interfaces
App.tsx Multi-plan state, localStorage persistence, file import/export
components/
Sidebar.tsx Personal info, Social Security, filing status
Main.tsx Tab bar, charts, and detail tables
AccountsTab.tsx Account balances, contributions, return assumptions (Basic/Advanced)
ExpenseTab.tsx Spending categories and itemized expenses (Basic/Advanced)
TipLabel.tsx Inline tooltip component
__tests__/
financial.test.ts Projection engine unit tests
optimizer.test.ts Optimizer unit tests
- Federal tax brackets, standard deductions, IRMAA tiers, and contribution limits use 2026 values, extrapolated forward where modeled by the app's inflation rate
- RMDs follow SECURE 2.0 rules using prior year-end balance; optional QCDs and an estimated joint-life adjustment are supported
- Basic Accounts and Expenses model combined household values; use Advanced views when ownership, start/end ages, or item-level timing matter
- Married plans can model separate spouse retirement age and spouse wages; existing plans without those fields keep the primary retirement age behavior
- Roth conversion taxes are modeled as paid from the taxable account
- IRMAA surcharges based on MAGI from 2 years prior (approximated from current-year income)
Issues and pull requests are welcome. See CONTRIBUTING.md for bug report guidance, PR expectations, and calculation-change notes.
If this app is useful, you can support ongoing development through the repository's Sponsor button.
MIT License. See LICENSE.
This project is an open-source educational planning model. It is not financial, tax, legal, or investment advice. Results depend on current-law assumptions, tax-year data, and your inputs. Validate important decisions with qualified professionals and official sources.