Skip to main content

Shared Services, Hooks, and Utilities Feature Context

Source: .agents/references/features/shared-services-hooks-and-utilities.md

Content​

Shared Services, Hooks, and Utilities Feature Context

Purpose​

Shared services, hooks, and utilities are cross-cutting infrastructure used by most product domains: service helpers, request wrappers, analytics, localization, storage wrappers, Sentry/PostHog, uploads, date/time helpers, route helpers, browser utilities, image sizing, safe rendering, and reusable hooks. Changes here have broad blast radius and require extra care.

User-Facing Workflows​

  • Most user-facing workflows indirectly rely on shared helpers for data fetching, auth, localization, analytics, uploads, error rendering, URL construction, and storage.
  • Shared hooks power pagination, query params, outside click detection, page leave warnings, uploads, unsplash search, chat widgets, and common public page data.
  • Utilities can run in browser, server, middleware, or test contexts. Verify runtime before using browser globals or Node/Bun APIs.

Key Entrypoints​

  • Services:
    • src/services/helpers/
    • src/services/commonService.js
    • src/services/uploadService.js
    • src/services/uploadImageService.ts
    • src/services/videoUploadService.js
    • src/services/sessionAnalytics/sessionAnalyticsService.js
    • src/services/notificationService.ts
    • src/services/unsplashService.ts
  • Hooks:
    • src/hooks/useApi.ts
    • src/hooks/usePagination.ts
    • src/hooks/useQueryParams.ts
    • src/hooks/usePresignedImageUpload.ts
    • src/hooks/useUnsplashSearch.ts
    • src/hooks/usePageLeaveWarning.ts
    • src/hooks/useOutsideComponentClickDetect.js
    • src/hooks/useRemoveScrollDuringOverlay.ts
    • src/hooks/useLogEvent.js
    • src/hooks/useLocale.js
    • src/hooks/useSentryReplayOnPage.js
  • Utilities:
    • src/utility/analytics.js
    • src/utility/analyticsConsts.js
    • src/utility/browserUtils.js
    • src/utility/config.js
    • src/utility/cookieService.ts
    • src/utility/dateHelper/
    • src/utility/domHelpers.js
    • src/utility/getImageUrlWithSizing.js
    • src/utility/helpers.ts
    • src/utility/intl.ts
    • src/utility/localStorageService.js
    • src/utility/localizationHelpers.js
    • src/utility/parseJSON.js
    • src/utility/routesHelper.ts
    • src/utility/safeErrorRender.tsx
    • src/utility/sentryService.ts
    • src/utility/sessionStorageService.js
    • src/utility/stringHelper.js
    • src/utility/urlHelpers.js
    • src/utility/validationHelper.ts

Data Flow and Service Boundaries​

  • Request helper changes can affect all service modules. Inspect callers and run lint/tests broadly when changing src/services/helpers/.
  • Browser storage must go through existing storage utilities; direct storage access violates repo rules and makes SSR/middleware behavior fragile.
  • Upload hooks/services often depend on presigned URL signatures, image/video compression, and external APIs. Preserve content type, file size, and error handling.
  • Analytics helpers should not expose secrets, tokens, or PII. Preserve event naming and action constants unless the task explicitly changes instrumentation.
  • Date/time helpers affect timezone-sensitive UI. Check tests in src/utility/dateHelper/ and adjacent utility tests when changing formatting or timezone logic.
  • Shared hooks should be runtime-safe and avoid unnecessary effects. If an effect is required for browser subscriptions or DOM APIs, keep cleanup explicit.

Conventions and Gotchas​

  • Prefer TypeScript for new shared files. For existing JavaScript utilities, keep the extension unless a migration is requested.
  • Avoid any, unsafe as, and non-null assertions in shared TypeScript. Fix types at boundaries.
  • Do not add thin index re-export files. Put implementation in the main file.
  • Do not introduce generic abstractions unless they remove real duplication across current callers.
  • Keep helpers pure where possible; side effects should be explicit in service/hook boundaries.
  • Shared changes should include focused tests when existing tests exist or when behavior is easy to cover.
  • .agents/rules/clean-typescript.mdc
  • .agents/rules/prefer-typescript-files.mdc
  • .agents/rules/no-type-assertion-as.mdc
  • .agents/rules/no-try-catch-service-api.mdc
  • .agents/rules/web-security.mdc
  • .agents/rules/bun-first.mdc
  • .agents/references/coding-standard/useeffect-guidance.md

Useful Searches​

rtk rg "authorizedRequest|publicAxiosRequest|localStorageService|sessionStorageService|showErrorToast|analytics|Sentry|PostHog|presigned|upload" src/services src/hooks src/utility
rtk find src/services/helpers src/hooks src/utility -maxdepth 3 -type f
rtk rg "describe\\(|it\\(|test\\(" src/utility src/hooks src/services

Update Triggers​

Update this reference when request helpers, storage wrappers, analytics utilities, upload services, shared hooks, localization helpers, or date/time utilities change.