1# Performance Rules
2 
3Review performance only where there is realistic impact. Do not request `memo`, `useMemo`, `useCallback`, virtualization, or caching as style preferences.
4 
5## Async Waterfalls
6 
7Flag:
8 
9- Awaiting remote feature flags or fetches before checking cheap synchronous conditions.
10- Sequential awaits for independent operations.
11- API routes or server components starting requests late when they could start early.
12- Nested per-item fetches running serially when each item can fetch in parallel.
13- Suspense boundaries that force the whole page to wait when a lower boundary could stream or isolate loading.
14 
15Prefer `Promise.all` for independent work and branch-local awaits for conditionally needed data.
16 
17## Bundle Size
18 
19Flag:
20 
21- Barrel imports from heavy libraries or `@langgenius/dify-ui`.
22- Dynamic paths that prevent static trace analysis.
23- Heavy components loaded eagerly when hidden behind a dialog, tab, command, or feature activation.
24- Analytics, logging, editor, visualization, or third-party SDK code loaded before it is needed.
25- Feature-local optional modules imported at top level only for rare flows.
26 
27Use direct imports and `next/dynamic` where the user-visible path benefits.
28 
29## Server Rendering
30 
31Flag:
32 
33- Request-specific mutable state stored at module scope in SSR/RSC paths.
34- Large duplicate data serialized across RSC/client boundaries.
35- Static I/O repeated per request when it could be hoisted safely.
36- Cross-request cache without a bounded invalidation strategy.
37- Server actions lacking API-route-equivalent auth checks.
38 
39Use request-scoped deduplication such as `React.cache()` when repeated server reads in one request are the problem.
40 
41## Re-rendering
42 
43Flag:
44 
45- Effects or subscriptions reading broad state when a derived boolean or narrower selector is enough.
46- Components defined inside components.
47- Derived rendering state stored in state/effects.
48- Non-primitive default props recreated for memoized children.
49- Expensive work recalculated on every render where it affects real interaction cost.
50- High-frequency transient values stored in state when refs or CSS variables would avoid render loops.
51 
52Do not flag simple primitive expressions wrapped or not wrapped in `useMemo`; prefer no memo for simple work.
53 
54Require stable object/array/function identity only when:
55 
56- The child is memoized and identity affects renders.
57- The value is an effect/query dependency.
58- A library API requires stable references.
59- Profiling or local behavior shows avoidable re-rendering.
60 
61## DOM, Lists, And Rendering
62 
63Flag:
64 
65- Layout reads in render (`getBoundingClientRect`, `offset*`, `scrollTop`).
66- Interleaved DOM reads/writes that can cause layout thrashing.
67- Large lists rendering without virtualization, pagination, or `content-visibility`.
68- SVG/animation code animating expensive properties when transform/opacity would work.
69- `transition-all`.
70- Long-running non-critical browser work performed immediately instead of idle/deferred scheduling.
71 
72## React Flow
73 
74For workflow React Flow components, keep this Dify-specific rule:
75 
76- UI consumption should use React Flow hooks such as `useNodes` / `useEdges`.
77- Callback-only reads or mutations can use `useStoreApi`.
78- Node components under `web/app/components/workflow/nodes/[nodeName]/node.tsx` must not depend on workflow stores that are absent in RAG Pipe template rendering.
79