claude-config

Fix TypeScript type inference loss when dynamically constructing Zod object schemas. Use when: (1) `z.infer<typeof schema>` produces `Record<string, unknown>` instead of typed fields, (2) Building a schema factory that constructs `z.object()` from dynamic field maps, (3) Component props typed from Zod schema show 'unknown' for all fields, (4) Type error "'data.fieldName' is of type 'unknown'" after refactoring schemas to use a factory pattern. Covers Zod 3 and Zod 4.

Access the Home Assistant REST API using environment variables HA_URL and HA_TOKEN exported in ~/.zshrc. Use when: (1) need to query Home Assistant entity states, (2) need to call HA services programmatically, (3) need to debug or inspect HA integration state, (4) user asks to interact with their Home Assistant instance. Covers authentication, common endpoints, and usage patterns.

Fix Better Auth performance anti-pattern: manual db.$setAuth() vs. reusing cached client. Use when: (1) Server actions or components create new auth contexts with db.$setAuth(), (2) Functions accept User parameter just to create auth context, (3) Dashboard or data-heavy pages are slow (>500ms), (4) Multiple sequential auth operations in same request. Applies to Better Auth v1.4.10+ with JWE cookie cache and ZenStack ORM.

Fix for "An error occurred in the Server Components render" in Next.js production builds when using ZenStack ORM with Better Auth. Use when: (1) Generic Server Components error in production with no stack trace, (2) Works in dev but fails in production, (3) Using manual db.$setAuth() instead of authenticated client from auth()/requireRole(). Symptoms include Sentry errors with digest but no details, or blank error pages. Solution: Always use the pre-configured db client from auth() or requireRole() result instead of manually creating auth context with db.$setAuth({ id, role }).

Fix timezone drift when using JavaScript Date methods with UTC-stored times. Use when: (1) Times shift by user's timezone offset (e.g., 09:00 UTC becomes 10:00 in BST browsers), (2) Database stores times in UTC but display shows wrong hours, (3) Inconsistent time behavior across users in different timezones, (4) Using getHours/getMinutes/setHours with Date objects that should stay in UTC. Replace local time getters/setters with UTC variants to prevent automatic timezone conversion.

Refactor Next.js + Better Auth authentication to minimal API with discriminated unions. Use when: (1) Too many auth helper functions causing maintenance burden, (2) Want perfect type safety without optional chaining, (3) Need to optimize auth performance with aggressive cookie caching, (4) Using Better Auth v1.4+ with Next.js 16 App Router and ZenStack ORM. Covers progressive refactoring from backward-compatible to breaking changes, discriminated union type patterns, and systematic multi-file migration.

Fix TypeScript errors when integrating react-big-calendar drag-and-drop addon in Next.js/React projects. Use when: (1) Getting "Module has no exported member 'EventInteractionArgs'" error, (2) EventWrapperProps type missing 'children' property causing type errors, (3) stringOrDate type mismatches in onEventDrop/onEventResize handlers. Covers proper type imports and generic type parameters for withDragAndDrop HOC.

Integrate react-big-calendar with Next.js 16 App Router and shadcn/ui. Use when: (1) Need to add a visual calendar to Next.js app, (2) Want calendar that works with server/client component split, (3) Need to integrate with shadcn/ui theming, (4) Building scheduling or availability features. Covers component structure, CSS imports in client components, date-fns localizer setup, and event styling with shadcn variables.

Properly render both recurring and one-off events in react-big-calendar with date constraints. Use when: (1) One-off events appear every week instead of just their specific date, (2) Recurring events don't respect effectiveFrom/effectiveUntil date ranges, (3) Calendar only shows current week instead of entire view range, (4) Need to generate events dynamically based on recurrence pattern and view range. Solves event generation for calendars with mixed recurring/one-off availability blocks.

Fix validation errors "Start time must be before end time" when seeding time-based data with timezone conversion. Use when: (1) Database seeding fails with time ordering validation errors despite correct local times, (2) Timezone conversion causes day-of-week changes that break time comparisons, (3) Early morning times (00:00-06:00) wrap to previous day after UTC conversion, (4) Seeding availability blocks, schedules, or recurring time-based data. Covers proper timezone conversion with day tracking and exclusive date ranges.

Fix ZenStack access control bug where cascading check(relation, 'read') policies allow unauthorized data access. Use when: (1) Users can see other users' private data they shouldn't access, (2) Access control works at User/Profile level but fails for related models, (3) Public profile access unintentionally grants access to private related data. Covers ZenStack @@allow policies with check() function and defense-in-depth patterns.

Fix TypeScript type errors when passing ZenStack query results to components expecting Zod schema types. Use when: (1) Getting "Type 'null' is not assignable to type 'undefined'" errors, (2) Database query results don't match component prop types, (3) ZenStack findMany/findFirst results have nullable fields but Zod schemas expect optional (undefined) fields, (4) Working with ZenStack + TypeScript in Next.js. Covers null vs undefined handling, type transformations, and proper interface definitions.

Fix buttons unintentionally submitting forms due to HTML's default type="submit" behavior. Use when: (1) Dismiss/cancel/close buttons trigger form submissions, (2) Modal/dialog buttons cause unexpected form submits, (3) Dropdown/toggle buttons submit parent forms, (4) Any interactive button inside a form triggers submission when it shouldn't. Solves the common gotcha where buttons without explicit type attributes default to type="submit" inside forms, causing confusing behavior. Covers HTML button elements, React components, and all web frameworks with form handling.

Fix Sentry integration issues in Next.js 16 with Turbopack. Use when: (1) Getting "Route used Math.random() before accessing uncached data" errors after adding Sentry, (2) Deprecation warnings about disableLogger/automaticVercelMonitors, (3) TypeScript errors about NextRequest type incompatibility with duplicate Next.js installations, (4) Build fails with OpenTelemetry-related errors. Covers Sentry SDK 10.x + Next.js 16 + Turbopack monorepo setup with proper configuration.

Fix React duplicate detection race conditions using useRef for synchronous checks. Use when: (1) Rapid successive function calls bypass duplicate/spam detection despite state-based checking logic, (2) Rate limiting or cooldown logic fails when triggered multiple times quickly, (3) Duplicate items appear in lists despite deduplication code, (4) State-based guards don't prevent re-entry in event handlers. Solves race condition where multiple calls read the same stale state value before any setState completes. Covers React hooks patterns with useRef, useState, useCallback for duplicate prevention, spam protection, rate limiting, and synchronous guard checks.

Fix TypeScript type errors in next-intl when translation keys don't match across locale files. Use when: (1) Getting "Types of property are incompatible" errors in i18n helper files, (2) Adding new translation sections and getting type errors, (3) Property missing errors across locale files, (4) Type errors mentioning specific translation keys after adding new translations. Covers next-intl with TypeScript in Next.js 13+ App Router projects.

Fix Next.js 16 build errors in "use server" files. Use when: (1) Build error "A 'use server' file can only export async functions, found object", (2) Need to export constants/enums from server action files, (3) Want to use next/headers without forcing entire module into dynamic rendering, (4) Server action helpers like error() or validateInput() fail type checking. Covers Next.js 16 strict requirements for server action files and dynamic import patterns.

Fix Next.js 16 build error "A 'use server' file can only export async functions, found object". Use when: (1) Build fails with this exact error message, (2) You have constants, enums, or type exports in files with "use server" directive, (3) Exporting AUDIT_ACTIONS, validation schemas, or other non-function values from server action files. Solution: Separate constants into a new file without "use server" directive and import them where needed.

Fix session invalidation detection in Next.js 16 App Router with Better Auth. Use when: (1) Signed-out header but protected content still visible after sign-out, (2) Session changes not detected until page interaction/reload, (3) E2E tests fail with "should maintain session after page reload" or similar session persistence tests, (4) Users can view dashboard content after signing out until they click something. Implements dual-layer auth: server-side check (initial render) + client-side monitoring (runtime invalidation detection) using Better Auth's useSession hook with proper polling configuration.

Fix React user preferences not persisting after page reload when loaded from database. Use when: (1) Settings load into state but don't appear in UI after reload, (2) User preferences exist in database but UI shows defaults, (3) Accessibility settings or theme preferences not applied despite being saved, (4) E2E tests fail expecting persisted settings. Covers React useEffect patterns for loading async data and applying DOM changes separately, preventing application during loading state.

Fix Vitest "PromiseRejectionHandledWarning" and flaky tests when testing retry logic with exponential backoff. Use when: (1) Testing setTimeout-based retry mechanisms with promises, (2) Getting unhandled promise rejection warnings with vi.useFakeTimers(), (3) Tests pass/fail inconsistently when using advanceTimersByTimeAsync, (4) Testing exponential backoff, rate limiting, or circuit breaker patterns. For simple retry logic with small delays (10-100ms), real timers often work better than fake timers due to microtask/macrotask coordination complexity.

Fix TypeScript circular reference errors when passing ZenStack authenticated database client as function parameter. Use when: (1) TypeScript error "TS2502: 'db' is referenced directly or indirectly in its own type annotation", (2) Utility functions need to accept authenticated db from server actions, (3) Using `ReturnType<typeof db.$setAuth>` causes circular reference. Solves typing authenticated ZenStack clients in Better Auth + ZenStack projects with proper access control enforcement.

Fix "INVALID_KEY: Namespace keys can not contain the character '.'" error in next-intl. Use when: (1) Getting INVALID_KEY error with dots in translation keys, (2) Migrating from flat key structure to next-intl, (3) Keys like "email.notification.booking" failing, (4) Error message lists specific keys with dots as invalid. Solution: Convert flat keys with literal dots to nested object structure. Applies to Next.js i18n with next-intl library.

Fix Next.js 16 build errors "Module not found: Can't resolve 'dns', 'fs', 'net', 'tls'" when client components import constants from files that transitively import Node.js modules. Use when: (1) Build fails with Node.js module resolution errors in client components, (2) Error trace shows [Client Component Browser] importing from a utility file, (3) Constants or shared code in a file with database/Prisma/server imports. Solves client/server boundary violations by extracting shared constants to isolated files.

Fix broken locale routing in Next.js apps using next-intl. Use when: (1) Links navigate without locale prefix (e.g., /dashboard instead of /en/dashboard), (2) Language preference lost on navigation, (3) 404 errors due to missing locale in URL, (4) Setting up new Next.js project with next-intl. Solves import of Link component from wrong module - must use @/i18n/routing instead of next/link.

Fix for user preference rate limiting bypass vulnerability. Use when: (1) Users can reset rate limits by toggling preference settings, (2) Cooldown tracking uses preference.updatedAt field, (3) Email/notification spam prevention fails after preference changes, (4) Rate limit state stored in same record as enabled/disabled preference. Covers messaging cooldowns, notification throttling, and any preference-based rate limiting system.

Mock Prisma/ZenStack queries when code uses both findFirst and findUnique on the same model. Use when: (1) Tests fail with "Cannot read property of undefined", (2) Code queries same model with different methods (findFirst for search, findUnique for exact match), (3) Mock returns undefined for one query type, (4) Single mockImplementation doesn't cover all cases. Covers Vitest + Prisma/ZenStack testing patterns with multiple query methods.

Discover actual ZenStack/Prisma relation field names when type errors occur. Use when: (1) TypeScript errors like "Property 'verificationRecord' does not exist" on model instances, (2) Runtime errors accessing relations, (3) Implementing new features that query related data. Solves the problem of mismatched assumptions about relation names vs actual schema-generated names.