Files
front-common-library/.agent/consumer.md

2.9 KiB

KriFrontCommon Consumer Contract

Package Usage

  • Consume this contract through the published @kri/common package and only through entry points declared in its package.json exports map.
  • Use the package root for runtime-neutral object, URL, date, string, and shared type utilities.
  • Use a focused subpath such as @kri/common/http, @kri/common/browser, @kri/common/server, @kri/common/security, @kri/common/hooks, @kri/common/query, @kri/common/config, @kri/common/jotai, or @kri/common/noti-hub for the corresponding capability.
  • Do not import from @kri/common/src/*, @kri/common/dist/*, or another undeclared deep path.
  • Do not copy or fork a shared utility locally merely to avoid using an available public entry point. Propose a backward-compatible library addition when the shared contract is genuinely missing.

Runtime and Optional Integrations

  • Keep browser, server, and runtime-neutral imports on their intended side of the application boundary.
  • A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point.
  • Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper.
  • Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value.
  • Prefer named public exports and retain the consumer project's current module system and bundler conventions.

React Compiler and Manual Memoization

  • createKriNextConfig enables reactCompiler: true unless the project overrides it; confirm the effective configuration.
  • When enabled, rely on React Compiler instead of adding useMemo, useCallback, or React.memo as a routine performance precaution.
  • Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem.
  • Preserve existing memoization unless approved and verified for removal. Use "use memo" or "use no memo" only for a documented compiler boundary.

Project Instruction Budget

  • Keep .agent/project.md at or below 8 KiB (8,192 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schemas, endpoint inventories, examples, and temporary issue history to linked project documentation, and keep concise read-routing instructions here.

Change Safety

  • Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes.
  • Review release notes and the actual affected API before upgrading. Run the consumer's focused type-check, test, and build commands after an upgrade.
  • Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.