fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add building-feature-ui guide and update agent instructions
Some checks failed
CI / typecheck + lint + boundaries + test + build (push) Has been cancelled
Details
CodeQL / Analyze (javascript-typescript) (push) Has been cancelled
Details
Coverage snapshot / snapshot (push) Has been cancelled
Details
Release Please / release-please (push) Has been cancelled
Details
Sentry PII guard (R31) / pii-guard (push) Has been cancelled
Details
CI / Playwright e2e (push) Has been cancelled
Details
CI / Storybook smoke tests + visual regression (push) Has been cancelled
Details
Mutation testing (nightly) / mutate (push) Has been cancelled
Details

Browse Source 
- New guide covers server/client component pattern, hooks, DI prefetch,
  HydrationBoundary hydration, core-ui atomic design reuse, Tailwind
  wiring, seed data, and cross-feature boundaries
- Update AGENTS.md with feature UI folder structure and naming rules
- Update CLAUDE.md with feature UI data fetching convention
This commit is contained in:
danijel-lf
2026-05-26 15:59:22 +02:00
parent 8bc32095c1
commit 6a5d602b3b
3 changed files with 521 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
AGENTS.md
View File

@@ -308,13 +308,31 @@ Each feature package exposes exactly these subpath exports:
| Subpath | What it exports | Who consumes |
| ---------------------- | -------------------------------------------------------------------------------------------------- | ----------------------- |
| `.` (root) | Contracts only: types, errors, schemas, `IUseCase` / `IController` aliases, router type, constants | Any consumer |
| `./ui` | Query builders (`queryOptions`), UI components | App packages |
| `./ui` | Hooks (`useX`), components, query builders (`queryOptions`) | App packages |
| `./api` | tRPC router (`xRouter` + `XRouter` type) | `@repo/core-api` only |
| `./cms` | Payload collections | `@repo/core-cms` only |
| `./di/bind-production` | App boot side-effect — swaps mock for real Payload impl | App packages only |
| `./di/bind-dev-seed` | App boot side-effect — swaps empty mock for populated mock | App packages, storybook |
Apps import schemas/types from `@repo/<feature>` (root) and React Query builders from `@repo/<feature>/ui`. Deep source paths are not accessible — the `exports` map enforces this.
Apps import schemas/types from `@repo/<feature>` (root) and hooks/components from `@repo/<feature>/ui`. Deep source paths are not accessible — the `exports` map enforces this.
### Feature UI structure
Each feature's `src/ui/` follows this layout:
```
src/ui/
index.ts # Barrel — exports server components as public API
query.ts # Query builder functions (framework-agnostic)
hooks/
use-<entity>.ts # "use client" — wraps useTRPC + useSuspenseQuery
components/
<entity>-list.server.tsx # Server — DI + prefetch + HydrationBoundary (public)
<entity>-list.client.tsx # "use client" — calls hook (internal only)
<entity>-card.tsx # Presentational (receives props)
```
Server components (`.server.tsx`) are the public API — the barrel exports them under clean names (`ArticleList`, not `ArticleListServer`). Client components (`.client.tsx`) are internal — only imported by their `.server` counterpart. Server components resolve controllers from DI, prefetch data, and wrap client components in `HydrationBoundary` for SSR + instant hydration. App pages just import and render: `<ArticleList />`, `<PageContent slug="about" />`. See [`docs/guides/building-feature-ui.md`](./docs/guides/building-feature-ui.md) for the full guide.
### Payload-backed features use constructor injection