CashTracker Frontend

Personal finance app built with Next.js 16 (App Router), React 19 and TypeScript. Users organise spending into envelopes, record expenses against them, and classify them with categories.

Ships in Spanish and English.

Requirements

• Node.js 22.x (>=22 <25)
• pnpm 11.x — the package manager is pinned in package.json, and the lockfile is pnpm-lock.yaml. Other package managers will resolve a different dependency tree, and CI installs with --frozen-lockfile.
• A running cashtracker-backend on port 4000
• A Clerk development instance

Setup

git clone https://github.com/Evhorus/cashtracker-frontend.git
cd cashtracker-frontend
pnpm install
cp .env.template .env      # then fill it in - see below
pnpm dev                   # http://localhost:4001

Environment

.env.template lists every variable. They are validated at boot by src/shared/config/env.server.ts, so an incomplete .env fails immediately with a message naming the variable rather than erroring later on some request.

Variable	What it is
API_URL	Backend base URL, e.g. http://localhost:4000/api
NEXT_PUBLIC_URL	This app's own origin — what sitemap.xml and robots.txt advertise
CLERK_SECRET_KEY	Clerk secret key (sk_test_…)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk publishable key (pk_test_…)
NEXT_PUBLIC_CLERK_SIGN_IN_URL	/sign-in — not optional: without it Clerk sends users to its own hosted page instead of this app's
NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL	Where a user lands after signing in
NEXT_PUBLIC_CLERK_SIGN_UP_FORCE_REDIRECT_URL	Where a user lands after signing up
E2E_CLERK_USER_EMAIL	Only for the signed-in e2e suite — point it at a dedicated test user

Commands

Command	What it does
pnpm dev	Dev server with Turbopack on port 4001
pnpm build / pnpm start	Production build / serve
pnpm typecheck	tsc --noEmit
pnpm lint	ESLint
pnpm format / pnpm format:check	Prettier write / verify
pnpm test / pnpm test:watch	Vitest
pnpm test:e2e	Playwright, signed-out suite
pnpm test:e2e:signed-in	Playwright, signed-in suite (needs the backend and a test user)

Tests

Vitest covers logic that would be expensive to get wrong — money formatting, calendar dates, pagination, status derivation, the price input's typing rules, and that the two message catalogues agree. It runs in about two seconds and is part of CI.

Playwright covers what only a browser can answer, split by what each suite costs to run:

• e2e/signed-out/ (pnpm test:e2e) — auth redirects, the locale cookie, page titles and the sign-in/sign-up forms. Needs Clerk keys and nothing else, so this suite runs in CI on every pull request.
• e2e/signed-in/ (pnpm test:e2e:signed-in) — envelope, expense and category lifecycles, plus form validation. Signs in once via a Clerk ticket (no password stored anywhere) and reuses the session. These tests create and delete real rows, so point E2E_CLERK_USER_EMAIL at a dedicated test account, never at production.

Which folder a spec lives in decides which suite runs it — both projects match by glob, so a spec is never silently left out.

Project structure

Domain-driven. Rather than a literal tree that goes stale with every feature, this is the pattern each business domain repeats — today envelopes, expenses, categories, dashboard, auth, account, home, locale:

This is the beginning of the README. Read the rest at the original. Read the full README ↗