Technology Stack & Constraints

Purpose

This file lists the MANDATORY technologies and libraries for this project. AI agents must strictly adhere to this stack. Do not introduce new dependencies without explicit permission.

Core Framework

Establish the host framework before following anything below. Helix is built and documented against Next.js App Router, but every TimelyCare platform app that consumes it — admin-web, campus-web, member-web, payment-web, provider-web — is a Vite SPA. Vite is the more likely case in practice. On Vite, skip every Server Component note (they are inert: everything is a client component) and register the @tailwindcss/vite plugin, which the Next.js path does not need. Framework-by-framework table: the helix-setup skill.

  • Framework: Next.js 14+ (App Router) for new greenfield apps; Vite + React for the existing platform apps
  • Language: TypeScript (.tsx, .ts)
  • Package Manager: npm or pnpm (Check lockfile)

styling

  • Engine: Tailwind CSS
  • CSS Variables: Carry the semantic tokens and drive light/dark mode. A single brand token set — no per-brand theme switching (see ./theme-strategy.md and ../tokens/colors.md).
  • Animation: tw-animate-css — imported in the app stylesheet, not registered as a plugin.
  • Icons: Lucide React (lucide-react)
    • Rule: NEVER import from other icon icons libraries (e.g. FontAwesome, Heroicons).
    • Rule: ALWAYS check ../icons/inventory.md if available, or assume standard Lucide names.

UI Component Library

  • Base: shadcn/ui
  • Primitives: Radix UI (headless accessible primitives)
  • Location: All components must live in @timelycare/helix-ui
  • Rule: Do not install full component libraries (MUI, Chakra, Mantine). Use the shadcn pattern of copying source code.

State Management

  • Server State: React Server Components (RSC) for fetching.
  • Client State:
    • React.useState / React.useReducer for local state.
    • nuqs (URL state) for searchable/filterable lists.
    • zustand for complex global client state (if needed).
  • Forms: react-hook-form + zod (Validation).

Data Fetching

  • Server: Direct DB calls in Server Components or Server Actions.
  • Client: tanstack-query (aka React Query) for client-side fetching/syncing if widely used interactively.

Testing (If applicable)

  • Unit: Vitest + React Testing Library
  • E2E: Playwright

Linting & Quality

  • Linter: ESLint (Next.js config)
  • Formatter: Prettier (Tailwind plugin enabled)