react-best-practices

name

react-best-practices

description

React performance and correctness rules tuned for silkdown — a CodeMirror 6 wrapper library, not a Next.js app. Auto-trigger when editing the React adapter (packages/react/src/SilkdownEditor.tsx, packages/react/src/index.ts), reviewing or refactoring any React component or hook in this repo, optimizing bundle budgets in size-limit, debugging unnecessary re-renders or stale closures around the EditorView, or adding lazy-loaded widgets (math/mermaid/table). Also fires on: "React perf", "useEffect", "memoization", "stale ref", "stale closure", "rerender", "useMemo", "useCallback", "forwardRef", "imperative handle", "bundle size", "tree-shaking", "barrel imports", "React.lazy", "controlled vs uncontrolled".

React Best Practices — silkdown edition

Adapted from Vercel Engineering's React performance guide. Aggressively pruned for this repo:

• Removed: every Next.js / SSR / hydration / RSC / server-action / next/script / next/dynamic rule, every client-swr-* and client-localstorage-* rule, every rendering-* rule (SVG animation, content-visibility, hydration scripts, resource hints, script tags — none of which apply to a CM6 wrapper), and the full js-* micro-optimization category (general perf tips, not React; profile decorate/* hot paths before optimizing them).
• Kept: rules that affect either (a) the React adapter wrapping EditorView, or (b) library bundle budgets enforced by pnpm size.

When to apply

Read these rules when:

• Touching packages/react/src/SilkdownEditor.tsx or any future framework adapter
• Adding lazy-loaded widgets (image/table/code/math/mermaid) — these affect both bundle-* rules and consumer bundle size
• Reviewing PRs for unnecessary re-renders, stale closures, or useEffect mistakes
• Auditing packages/core/dist/index.js against its 30 KB limit or packages/react/dist/index.js against its 5 KB limit (pnpm size)
• Building example apps in examples/ that demonstrate idiomatic library usage

Rule categories (priority order)

Priority	Category	Why it survived the prune
1	Bundle Size (bundle-*)	The library has hard size-limit budgets; tree-shaking and lazy loading are non-negotiable.
2	Re-render Optimization (rerender-*)	The React adapter must not invalidate EditorView on parent renders, and consumers will copy our patterns.
3	Advanced (advanced-*)	All four of these directly describe the CM6-wrapper pattern (refs for handlers, init-once, useLatest, effect-event deps).
4	Async (async-*)	A few rules apply to tests and lazy-widget loading.
5	Client-side (client-*)	Two rules about DOM event listeners — relevant because CM6 attaches them.

Quick reference

1. Bundle Size (CRITICAL)

• bundle-barrel-imports — Import directly; barrel files defeat tree-shaking and break our 30 KB / 5 KB budgets.
• bundle-dynamic-imports — React.lazy for heavy widgets (math, mermaid, large code-fence renderers).
• bundle-conditional — Load widget renderers only when their feature is activated by silkdown() options.
• bundle-preload — Preload widget code on hover/focus for perceived speed.

2. Re-render Optimization

• rerender-defer-reads — Don't subscribe to state only used in callbacks.
• rerender-memo — Extract expensive work into memoized components.
• rerender-memo-with-default-value — Hoist default non-primitive props (e.g. default extensions={[]}).
• rerender-dependencies — Use primitive dependencies in effects; the adapter's value prop dep is a string by design.
• rerender-derived-state — Subscribe to derived booleans, not raw values.
• rerender-derived-state-no-effect — Derive state during render, not in effects.
• rerender-functional-setstate — Functional setState for stable callbacks.
• rerender-lazy-state-init — Pass a function to useState for expensive init.
• rerender-simple-expression-in-memo — Avoid useMemo for primitive-returning expressions.
• rerender-split-combined-hooks — Split hooks with independent dependencies.
• rerender-move-effect-to-event — Put interaction logic in event handlers (CM6 already gives us update listeners — use them, don't re-derive in effects).
• rerender-transitions — Use startTransition for non-urgent updates.
• rerender-use-deferred-value — Defer expensive renders to keep input responsive.
• rerender-use-ref-transient-values — Refs for transient frequent values (this is exactly how viewRef works in SilkdownEditor.tsx).
• rerender-no-inline-components — Don't define components inside components.

3. Advanced (all directly describe the CM6 wrapper pattern)

• advanced-effect-event-deps — Don't put useEffectEvent results in effect deps.
• advanced-event-handler-refs — Store event handlers in refs. This is exactly how onChangeRef works in SilkdownEditor.tsx — keeps onChange referentially stable so the editor doesn't recreate when the parent re-renders.
• advanced-init-once — Initialize the editor once per mount (empty deps array on the mounting effect).
• advanced-use-latest — useLatest pattern for stable callback refs.

4. Async

• async-cheap-condition-before-await — Check cheap sync conditions before awaiting (e.g. compare existing doc string before dispatching).
• async-defer-await — Move await into the branch where it's actually used.
• async-parallel — Use Promise.all() for independent operations (matters in tests, builds, and any future multi-language code highlighter init).

5. Client-side

• client-event-listeners — Deduplicate global event listeners. CM6 attaches DOM listeners; if we add document-level listeners (e.g. for clipboard hooks) they must be deduped.
• client-passive-event-listeners — Use passive listeners for scroll. Relevant for any scroll-syncing widgets.

How to use

Each rule lives in rules/<rule-name>.md with: brief explanation, incorrect example, correct example, additional context. Open the file matching the situation — these are not all loaded eagerly.

Why some rules are gone

If you came looking for a rule and don't see it:

• rendering-hydration-*, rendering-script-defer-async, rendering-resource-hints: This is a library, not an SSR app. Hydration and <script>/<link> tags don't apply.
• client-swr-dedup, client-localstorage-schema: We don't fetch and we don't persist user data.
• bundle-defer-third-party: We have no analytics/logging dependencies.
• async-suspense-boundaries, async-dependencies: Suspense isn't used; the editor mounts synchronously.
• rendering-svg-precision, rendering-animate-svg-wrapper: No SVG.
• All js-* rules: General JS micro-perf, not React-specific. Profile decorate/* hot paths before optimizing them — speculative wins aren't worth the readability cost.

If a removed rule turns out to apply later (e.g. we add an SSR-aware adapter), restore it from the upstream Vercel guide.