service-development

Service Development

When to use

• Creating a new service (copy _template/service into app/features/services/<serviceName> and rename Sample placeholders).
• Updating container/store/structure/lib/constants for an existing service while keeping template rules intact.
• Removing an existing service and its wiring from store/actions via CLI.

Quick start

0. Scaffold via CLI:
   • ill addService auth
   • or ill addService --name auth
   • Add --no-store if the service does not need a Redux slice/store wiring.
1. Keep export surface the same (index.tsx re-exports store/constants/lib and exposes { service: useContainer } from a lowercase export).
2. Replace placeholder DTO/UI types, schemas, and data models; move every magic number/string into constants/ and re-export via constants/index.ts.
3. If the service is global (app-wide side effects), register it in the root ServiceInjector services list.
4. Remove via CLI when needed:
   • ill removeService auth
   • or ill removeService --name auth

File roles and guardrails

• container (container/index.ts)

  • Hook signature stays useContainer: SC; no props passed.
  • Comment every logical block with // Описание: Начало/Конец; do not comment the return; update comments instead of deleting.
  • Naming: camelCase vars/functions, PascalCase components/types, booleans with is/has/should/can; handlers named on***Handler; use meaningful names.
  • No useCallback/useMemo (React compiler handles it).
  • Constants in SCREAMING_SNAKE_CASE under constants/ with barrel re-export; no inline magic literals.
  • If the service talks to backend and you map data between layers, keep transformations in lib/mappers (do not do mapping in container).

• index.tsx

  • Must export a lowercase service object to avoid collisions with widgets:
    • export const auth = { service: useContainer }
  • Re-export constants, store, lib to support useAppActions auto-binding.

• store/index.ts

  • Only reducers inside createSlice; no extra functions.
  • initialState imported from structure; do not type initialState.
  • Re-export via Actions and Reducer (used by useAppActions and store assembly).

• structure/index.ts

  • Holds initialState only; no functions; no type declaration for the state object.

• lib/types

  • Use type aliases (no interfaces) with Type suffix; enums with Enum suffix.
  • No function type definitions here; boolean names with is/has/should/can.
  • Put request/response DTO adapters here if service interacts with API/persistence.

• lib/mappers

  • Sole place for DTO ↔ internal model transformations; return Nullable where appropriate.

• lib/schemas

  • Yup schemas for forms/validation when needed; keys should be enums from lib/types.

• lib/utils

  • Lightweight helpers that consume typed data; magic values go to constants/.

• constants/

  • SCREAMING_SNAKE_CASE, meaningful names, no single-letter or cryptic abbreviations; re-export through constants/index.ts.
  • name.ts builds a service name from NAME_FROM_PACKAGE_JSON (service naming, not widget naming).

Store and actions wiring

If you scaffolded without --no-store, the CLI will auto-inject:

• Reducer import + reducer key into app/application/store/reducers.ts under // Services: Начало
• Actions binding into app/utils/hooks/useAppActions.ts

If you scaffolded with --no-store:

• CLI will NOT inject reducer/hooks. Keep the service free of Redux usage (or wire it manually if you later add a slice).

Do not confuse templates

• repo root _template/service/*: scaffolding templates used by ill addService
• widget-local templates/*: UI decomposition pieces used by widgets (not applicable to services)

Final checks

• Comments preserved/updated per template; no inline magic values; types/mappers/schemas/constants live in their dedicated files.
• Export name casing: service export is lowercase in index.tsx.
• If the service is app-global: it is included in the ServiceInjector list in /app/root.tsx.