A modern web application to calculate CPF (Central Provident Fund) contributions and project retirement balances following the 2023 income ceiling changes announced by Singapore's Ministry of Finance.
- 💰 Accurate CPF Calculations - Compute employee and employer contributions based on current income ceilings
- 📊 Age-Based Rates - Automatic calculation using 8 different age brackets with varying contribution rates
- 📈 Distribution Breakdown - View OA (Ordinary Account), SA (Special Account), and MA (MediSave Account) allocations
- 🔮 Retirement Projection - Project your CPF balances to age 55, 65, or 70 with CPF LIFE estimates and optional housing, top-up, and OA to SA assumptions
- 🧪 What-If Simulator - Compare salary changes, OA to SA transfers, annual top-ups, and the cost of starting later
- 🔗 Shareable URLs - Copy projection and what-if links with the current inputs already encoded in the URL
- 🛟 CPF LIFE Estimator - Estimate monthly CPF LIFE payouts from your Retirement Account balance and compare the main plan types
- 🧾 CPF Cheat Sheet - Download a printable PDF with contribution rates, account distribution, retirement sums, BHS, and PR reference points
- ✅ Retirement Readiness Score - Answer 5 quick questions to see which CPF planning gap to fix next and get a tailored follow-up report by email
- 🕒 Interactive Timeline - Visualise CPF income ceiling changes from 2023 to 2026 with an interactive timeline
- 📱 Mobile-Friendly - Responsive design with PWA support for offline use
- 📄 PDF Export - Download your CPF calculation results as a PDF document
- 🎨 Modern UI - Built with Next.js 16, React 19, and Tailwind CSS
- ⚡ Fast & Lightweight - Optimized performance with Turbopack
Following the Ministry of Finance announcement at Singapore Budget 2023 (13 February 2023), the CPF income ceiling is being progressively raised:
- Previous ceiling: $6,000 (before September 2023)
- Current target: $8,000 (by September 2026)
This calculator helps Singaporeans estimate their take-home income after CPF contributions under the new ceiling structure while accounting for age-specific contribution and distribution rates. It also includes a CPF projection page for modelling how your balances may grow across OA, SA, MA, and RA over time.
The core calculators and planning tools work without sign-up. Email is only requested if you want SimplyCPF to send you a cheat sheet or readiness report.
- Framework: Next.js 16 with React 19
- Language: TypeScript
- Styling: Tailwind CSS 4.x with HeroUI theme tokens
- State Management: Zustand
- UI Components: HeroUI v3 (
@heroui/react) and HeroUI Pro - Charts: HeroUI Pro chart wrappers (Recharts underneath)
- Testing: Vitest with React Testing Library
- Linting: Biome
- Package Manager: pnpm 11.x (RC)
- Deployment: Vercel
- Node.js 22+
- pnpm 11.x (RC, automatically enforced via
packageManagerfield)
# Clone the repository
git clone https://github.com/ruchernchong/simplycpf.git
cd simplycpf
# Install dependencies (Husky hooks initialise automatically via the `prepare` script)
pnpm install
# Start development server via Portless
pnpm dev
# Start development server without Portless
PORTLESS=0 pnpm devThe application will be available at https://simplycpf.localhost by default, or http://localhost:3000 when Portless is disabled.
API rate limiting is enabled when these Upstash Redis variables are configured. Without them, local and preview environments fail open and skip rate limiting.
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=# Start development server via Portless
pnpm dev
# Start development server without Portless
PORTLESS=0 pnpm dev
# Build for production
pnpm build
# Start production server
pnpm start
# Run linting
pnpm lint
# Type checking
pnpm typecheck
# Run tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Generate coverage report
pnpm test:coverageThe application includes a comprehensive API documentation portal at /docs with:
- Getting Started - Quick start guide for developers
- API Reference - Complete documentation for all 14 CPF endpoints
- Examples - Code samples in JavaScript/TypeScript and Python
- Changelog - Version history and updates
The site provides LLM-friendly endpoints following the llms.txt specification:
/llms.txt- Agent index with when-to-use guidance, API examples and limits/openapi.json- OpenAPI 3.1 specification for all 14 public CPF endpoints/index.md- Markdown homepage overview/llms-full.txt- Extended site reference and CPF background/cpf-rates.md- Reference tables generated from application constants/docs/llms-full.txt- Complete documentation in plain text format
The homepage and /docs pages negotiate HTML or Markdown using the Accept header, honour quality values and return 406 when neither representation is acceptable. Both variants include Vary: Accept, Accept-Encoding. Missing URLs requested as Markdown return a real 404 with recovery links; browser requests retain the existing error page.
With pnpm dev running through Portless, verify public documents and CPF API operations with:
node scripts/verify-agent-readiness.mjs https://simplycpf.localhostThe verifier requires curl, spaces API calls to respect rate limits, and can also target a deployed origin. Production canonical URLs default to https://simplycpf.com; local URLs follow PORTLESS_URL. NEXT_PUBLIC_BASE_URL overrides either.
Search ranking also requires external indexing and brand signals. After deployment, submit the sitemap and inspect the apex homepage in Google Search Console and Bing Webmaster Tools. Keep owned profile links consistent with https://simplycpf.com; add only verified organisation details. These steps require the owner's accounts and cannot guarantee a search position.
| Category | Endpoints |
|---|---|
| Calculation | /calculate, /calculate/batch, /projection |
| Age Groups | /age-groups, /age-group/find, /age/from-birthdate |
| Retirement reference | /retirement-sums, /bhs |
| Income Ceiling | /ceiling, /ceiling/timeline |
| Interest Rates | /interest-rates, /interest-rates/smra, /interest-rates/trend |
| Investment | /investment-comparison |
src/
├── app/ # Next.js App Router (routes, layouts, API)
│ ├── (main)/ # Product routes
│ ├── (docs)/ # Developer portal (Fumadocs, URLs under /docs)
│ └── api/ # REST API route handlers
├── components/ # Feature UI (folders match route names)
│ ├── shared/ # SplitBar, Wordmark, Logo, ErrorFallback, …
│ ├── calculator/
│ ├── projection/
│ ├── cpf-at-55/
│ └── …
├── stores/ # Zustand CPF store + selectors
├── providers/ # CpfStoreProvider
├── hooks/ # React hooks
├── lib/ # Calculation logic and utilities
├── data/ # CPF age groups and rates data
├── constants/ # Income ceilings, BHS, retirement sums, …
├── types/ # TypeScript type definitions
├── config/ # Application configuration
└── proxy.ts # Rate limit, CSP, LLM markdown negotiation
content/
└── docs/ # Developer portal MDX content
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- CPF contribution rates and distribution data sourced from Singapore's CPF Board
- Income ceiling changes based on Ministry of Finance Budget 2023 announcements
Ru Chern Chong
Made with ❤️ for the Singapore community