Code Conventions

Path Alias

@/* maps to ./src/*. All imports use this alias:

import { get } from "@/helpers/api";
import { cn } from "@/lib/utils";

Config Location

Application configuration lives in src/config/config.ts (not src/lib/config.ts). This file exports:

• getApiUrl(locale) / getLegacyApiUrl(locale) — API base URLs
• MAPBOX_ACCESS_TOKEN — Mapbox GL token (hardcoded)
• FINIX_ENVIRONMENT / FINIX_APPLICATION_ID — Finix payment config
• CAREER_URL — Careers page URL

Styling

• Tailwind CSS 4 with PostCSS
• Shadcn/UI components (New York style variant)
• Global styles in src/app/globals.css
• Always use the cn() utility from src/lib/utils.ts for conditional class merging:

import { cn } from "@/lib/utils";
 
<div className={cn("base-class", isActive && "active-class")} />

cn() combines clsx and tailwind-merge to handle Tailwind class conflicts.

Forms

• React Hook Form 7 for form state management
• Zod for validation schemas
• @hookform/resolvers to connect Zod schemas with React Hook Form
• Shared schemas live in src/lib/schemas/
• The useBillsForm hook in src/hooks/use-bills-form.ts is an example of the pattern

Icons

Three icon sources:

1. Lucide React (lucide-react) — Primary UI icons
2. FontAwesome (@fortawesome/react-fontawesome) — Brand icons and solid icons
3. Custom SVGs — Feature-specific icons in src/features/icons/

Font

The app uses Poppins loaded via next/font/google in the root layout. All text inherits this font.

Locale Utilities

• getCurrentLocale(pathname) from src/lib/utils/locale.ts — Extracts locale from pathname in client components
• getLocaleAwareHref(href, locale) from src/lib/utils.ts — Prepends locale prefix to hrefs
• LOCALES from src/lib/utils/locale.ts — Array ["us", "uk"]
• DEFAULT_LOCALE from src/lib/utils/locale.ts — "us"

Animations

Motion (formerly Framer Motion) is used for page transitions and hero animations. The motion package is imported from motion/react:

import { motion } from "motion/react";

Known Typo

src/lib/utils/contstants.ts (should be “constants”) contains app store URLs. This filename typo is known and has not been renamed to avoid churn.