CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

pnpm dev        # Start dev server with Turbopack
pnpm build      # Production build
pnpm lint       # Run ESLint
pnpm start      # Start production server

Architecture

This is a Next.js 16 App Router single-page app — a subscription cost calculator. There are no API routes; everything runs client-side.

Data flow:

• lib/services.ts — single source of truth for all subscription data. Exports subscriptionData (nested object: category → serviceId → Service), categoryConfig (maps category keys to display labels/icons), and all TypeScript types.
• lib/hooks/use-calculator-state.ts — custom hook that manages all calculator state (selected services, currency, sharing counts, custom services). Persists to localStorage and supports URL-based ?config= sharing.
• lib/hooks/use-persisted-state.ts — generic hook for localStorage-backed state with SSR-safe hydration. Skips localStorage when URL config is present.
• components/calculator.tsx — "use client" component. Uses useCalculatorState hook for interactive state. Reads from subscriptionData and categoryConfig to render the accordion/button UI and cost table.
• components/collapsible-info-panel.tsx — "use client" component. Wraps the two-column layout with a collapsible info card (persisted collapse state).
• app/page.tsx — server component. Renders <CollapsibleLayout> with the info card and <SubscriptionCalculator />.

Adding/updating services: Edit subscriptionData in lib/services.ts. Each service needs name, monthly_cost: { USD, EUR }, and plan. Set EUR to 0.0 and add note: "Not available in EU" for US-only services.

Adding a category: Add to the subscriptions object in subscriptionData, add a matching entry in categoryConfig with a label and Lucide icon, and extend the SubscriptionData interface type.

UI components live in components/ui/ — these are shadcn/ui-style components (Accordion, Badge, Button, Card, Select, Table, ThemeProvider). components/typography.tsx exports typed wrappers (H1–H4, P, A, Blockquote, List, InlineCode) for consistent styling.

Styling: Tailwind CSS v4 with tw-animate-css. The cn() utility in lib/utils.ts combines clsx + tailwind-merge. Fonts: Geist Sans, Geist Mono, Lora Serif (via CSS variables).

Theme: next-themes with system default, applied via ThemeProvider in app/layout.tsx.

Service icons are loaded from cdn.simpleicons.org using the lowercased, space-stripped service name. imageErrors state in the calculator falls back to a Building2 icon on load failure.