UNPKG

@augmentcode/ag-redux-toolkit

Version:

Redux + Saga state management for Svelte apps — designed for AI agents. Includes runtime TypeScript source, AI skills, and reference documentation for robust, observable, high-performance state management.

137 lines (119 loc) • 7.28 kB
--- name: react/migration description: >- React migration/adoption playbook for moving shared React state, context/hooks, external store subscriptions, useMemo derivations, and useEffect side effects to ReactStore, selectors, actions, reducers, and sagas. Documents which Svelte store/rune migration concepts are non-applicable to React. type: lifecycle requires: - react sources: - ./assessment/SKILL.md - ./setup/SKILL.md - ./writable-stores/SKILL.md - ./derived-stores/SKILL.md - ./side-effects/SKILL.md - ./component-migration/SKILL.md - ./cleanup/SKILL.md triggers: - React migration - migrate React state - replace React context state - migrate useEffect side effect - ReactStore adoption --- # React migration — React state/context/effects to ReactStore Use this index when a React app is adopting `ag-redux-toolkit` and the current state owner is `useState`, `useReducer`, React context, custom hooks, external stores, component `useMemo` derivations, or `useEffect` side effects. ## React migration policy 1. **ReactStore owns shared, persisted, or async-driven state.** Anything read or written by multiple components, synced to storage/server/IPC, or coordinated with async flows moves to actions, reducers, selectors, and sagas. 2. **Component-local ephemeral UI state stays local.** Hover, focus, transient form drafts, uncontrolled input details, scroll position, and single-component toggles can remain in React component state. 3. **Selectors own shared derivations.** Move duplicated `useMemo`, derived custom hook return values, and context selector logic into `ReactStore.createSelector`. 4. **Sagas own shared side effects.** Move persistent subscriptions, fetches, debounces, timers, storage sync, and cross-feature effects out of components. Migrate one state owner/slice at a time. Keep the app on the React Store family: `ReactStore`, direct Preact React selector signals as the preferred React consumer path, `.useValue(...args)` only for necessary hook/plain-value fallback paths, and `.select(state, ...args)` for composition and tests, and `.effect(...args)` for sagas. Svelte migration primitives are contrast-only here. Do not copy `writable`, `derived`, `$state`, `$derived`, `$effect`, `$selector` template, `+layout.svelte`, `onDestroy`, or Svelte context examples into a React migration. ## React migration leaf routes | Route | Svelte parity leaf | React applicability | | --- | --- | --- | | `./assessment/SKILL.md` | `../../svelte/migration/assessment/SKILL.md` | Applicable: inventory shared React local state, context/hooks, external stores, derivations, effects, and consumers. | | `./setup/SKILL.md` | `../../svelte/migration/setup/SKILL.md` | Applicable via `../../setup/SKILL.md` and `ReactStore`; Svelte `+layout.svelte` bootstrap is not applicable. | | `./writable-stores/SKILL.md` | `../../svelte/migration/writable-stores/SKILL.md` | Applicable by concept: mutable shared React state maps to actions/reducers; Svelte `writable`/`$state` are not React primitives. | | `./derived-stores/SKILL.md` | `../../svelte/migration/derived-stores/SKILL.md` | Applicable by concept: shared derivations map to `ReactStore.createSelector`; Svelte `derived`/`$derived` are not React primitives. | | `./side-effects/SKILL.md` | `../../svelte/migration/side-effects/SKILL.md` | Applicable by concept: shared/persistent/async effects move to sagas; Svelte `$effect` is not a React primitive. | | `./component-migration/SKILL.md` | `../../svelte/migration/component-migration/SKILL.md` | Applicable as JSX/TSX consumption swap using direct selector signals first, `.useValue(...args)` only for necessary plain-value fallback reads, and Store dispatch; Svelte templates/readables are not applicable. | | `./cleanup/SKILL.md` | `../../svelte/migration/cleanup/SKILL.md` | Applicable: remove old state owners/import paths and document shims/rollback; `.store.svelte.ts` cleanup is Svelte-only. | ## Recommended order 1. `assessment` — inventory React state owners, derivations, effects, and consumers; classify shared vs component-local. 2. `setup` — choose `ReactStore`, create the app store, initialize/dispose at the app owner, and start app sagas with `reactStore.runSaga(sagaFn)`. 3. `writable-stores` — move shared mutable React state to serializable slice state, actions, and pure reducers. 4. `derived-stores` — move shared derivations to selectors, compose with `.select(state, ...args)`, consume in components with direct selector signals first, and unit-test with `.select`. 5. `side-effects` — move shared or async effects to sagas. 6. `component-migration` — replace component/context/custom-hook reads with direct selector signals where possible, `.useValue(...args)` only where plain values are necessary, and Store-first dispatch. 7. `cleanup` — remove old providers/hooks/state owner modules after verification. ## Quick reference | React source pattern | ReactStore target | | --- | --- | | Shared `useState` / `useReducer` state | Slice initial state + actions + reducer | | Context provider that stores business state | `ReactStore` reducer map + selectors/actions | | Custom hook exposing shared mutable state | Direct selector signals + action dispatch helpers; `.useValue(...args)` only for plain-value hook contracts | | External mutable store subscription | Reducer state + saga/channel integration as needed | | Repeated `useMemo`/derived hook value | `reactStore.createSelector(...)` | | `useEffect` fetch/timer/storage sync | Saga with `takeEvery`/`takeLatest`, `call`, `put`, `delay` | | Component render read | `selectFoo(...args)` signal first; `selectFoo.useValue(...args)` only for necessary plain values | | Handler/test/composition read | `selectFoo.select(reactStore.state, ...args)` | ## Orchestration example ```ts type ReactMigrationStep = | "setup" | "writable-stores" | "derived-stores" | "side-effects" | "component-migration" | "cleanup"; type ReactStateAssessment = { owner: string; verdict: "reactstore" | "local"; patterns: Array<"useState" | "useReducer" | "context" | "useMemo" | "useEffect">; consumers: string[]; }; const cartAssessment: ReactStateAssessment = { owner: "src/cart/CartProvider.tsx", verdict: "reactstore", patterns: ["context", "useReducer", "useMemo", "useEffect"], consumers: ["CartSummary.tsx", "HeaderCartButton.tsx", "Checkout.tsx"], }; const nextSteps: ReactMigrationStep[] = cartAssessment.verdict === "reactstore" ? ["setup", "writable-stores", "derived-stores", "side-effects", "component-migration", "cleanup"] : ["cleanup"]; ``` ## Verification cues - React examples import `ReactStore` from `@augmentcode/ag-redux-toolkit/react-store` and keep selectors Store-bound. - Components/custom hooks consume migrated shared state with direct selector signals first; `.useValue(...args)` appears only for documented plain-value fallbacks. - Selectors compose and tests assert with `.select(state, ...args)`. - Sagas read migrated state with `.effect(...args)` and start via `reactStore.runSaga(sagaFn)` after `init()`. - Svelte store/rune/template/lifecycle concepts appear only as non-applicable contrasts, not active React instructions.