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.

228 lines (178 loc) • 8.36 kB
--- name: react/component-integration description: >- ReactStore component integration guidance for React app/root wiring. Covers where to create/configure ReactStore, init/dispose ownership, app saga startup with reactStore.runSaga(sagaFn), direct selector signal reads in JSX/TSX, selector .useValue(...args) fallbacks for hook/plain-value boundaries, and Store-first dispatch without Svelte or StreamingStore lifecycle rules. type: sub-skill requires: - react - react/store - react/selector-lifecycle sources: - "@augmentcode/ag-redux-toolkit/react-store" - ../selector-lifecycle/SKILL.md - ../store/SKILL.md triggers: - React component integration - ReactStore component wiring - TSX Store dispatch - selector .useValue component --- # React component integration — ReactStore app wiring Use this skill when a React/TSX app has chosen the `ReactStore` family. Create one configured `ReactStore`, initialize it before React renders selector-using components, start app sagas after initialization, and dispatch through that same configured store instance from components and handlers. This is React Store family guidance. For the same app/package/code path, do not apply Svelte readable/template/context lifecycle rules or `StreamingStore`/Kefir observable patterns. If a mixed repository has a separate Svelte or Node/server app, route that app to its own Store-family skill independently. ## 1. Create and configure the app `ReactStore` Create the store in an app-owned module, not inside a component render or custom hook. Pass app-owned reducers in the constructor map, optional middleware as the second argument, and options such as `throttledSelectorFrequency` as the third argument when needed. ```ts // src/store/react-store.ts import { ReactStore } from "@augmentcode/ag-redux-toolkit/react-store"; import type { StoreState } from "@augmentcode/ag-redux-toolkit/types"; import { todosReducer } from "./todos/todos-slice"; export const reactStore = new ReactStore({ todos: todosReducer }); export type AppState = StoreState<typeof reactStore>; ``` Key rules: - Use `ReactStore` only from `@augmentcode/ag-redux-toolkit/react-store` for this React apppath. - Use `reactStore.createSelector(...)` for app-local selectors so state inferencefollows the configured store. - Do not add package-owned `@internal_` reducers or internal sagas. - Do not create a new `ReactStore` per component, route, hook call, or render. ## 2. Initialize before React renders selector users Call `reactStore.init(initialState?)` once at the app bootstrap/root ownership boundary before rendering components that call direct signal selectors or `.useValue(...args)` fallbacks. The returned disposer is equivalent to `reactStore.dispose()`. ```tsx // src/main.tsx import React from "react"; import { createRoot } from "react-dom/client"; import { App } from "./App"; import { reactStore } from "./store/react-store"; const root = createRoot(document.getElementById("root")!); const disposeStore = reactStore.init(); root.render( <React.StrictMode> <App /> </React.StrictMode> ); if (import.meta.hot) { import.meta.hot.dispose(() => { root.unmount(); disposeStore(); }); } ``` Pass preloaded state to `reactStore.init(preloadedState)` when the app needshydration. Initialize before selector reads because `ReactStore.getSignalState()`throws before `init()` and after `dispose()`. ## 3. Dispose at the same owner boundary The owner that calls `reactStore.init()` owns teardown. In browser apps this isusually the bootstrap file or test harness; in embedded/micro-frontend apps it maybe the host's mount/unmount adapter. ```tsx export function mountReactApp(container: HTMLElement) { const root = createRoot(container); const disposeStore = reactStore.init(); root.render(<App />); return () => { root.unmount(); disposeStore(); }; } ``` Do not hide `init()` in a child component `useEffect` if descendants render selectors immediately; effects run after render, too late for direct signal selectors or `.useValue(...args)` fallbacks that need the initialized store. ## 4. Start app sagas with `reactStore.runSaga(sagaFn)` `reactStore.init()` starts package-owned runtime work but does not auto-start appsagas. Start each app saga explicitly after initialization and keep the returnedcancel function when the saga has a shorter lifetime than the whole store. ```ts // src/main.tsx import { reactStore } from "./store/react-store"; import { todosSaga } from "./store/todos/sagas/todos-saga"; const disposeStore = reactStore.init(); const cancelTodosSaga = reactStore.runSaga(todosSaga); export function disposeAppRuntime() { cancelTodosSaga(); disposeStore(); } ``` `reactStore.runSaga(sagaFn)` throws if `init()` has not been called or the saganame is reserved for package internals. Do not start `@internal_sagaManager`directly. ## 5. Read state in components with direct selector signals React components and custom hooks should prefer direct selector calls and pass/read the returned `ReadonlySignal<R>` where the Preact React signal integration supports it. Use `.useValue(...args)` only for third-party components, existing boundaries, or hook contracts that require a plain value and are impractical to adapt. ```tsx import { reactStore } from "../store/react-store"; import { selectTodoById } from "../store/todos/todos-selectors"; import { toggleTodo } from "../store/todos/todos-slice"; export function TodoRow({ id }: { id: string }) { const todo = selectTodoById(id); if (!todo.value) return null; return ( <button onClick={() => reactStore.dispatch(toggleTodo(id))}> {todo.value.completed ? "✓" : "○"} {todo.value.title} </button> ); } ``` Component rules: - Prefer direct selector calls for signal-aware components and custom hooks. - Use `.useValue(...args)` only in React components or custom hooks that truly need a plain value. - Import or otherwise receive the configured `ReactStore` instance and dispatchwith `reactStore.dispatch(action)` in event handlers. - Use `.select(reactStore.state, ...args)` for one-shot reads inside handlers,callbacks, tests, or pure composition. - Do not use `.useValue(...args)` as the default just to avoid adapting a consumer to accept a Preact React signal object. ## 6. Event-handler one-shot reads Handlers should not call `.useValue(...args)` and should not create direct signals just to read once. Use `.select(state, ...args)` with the initialized app store state already in scope, then dispatch through the configured store. ```tsx function DeleteTodoButton({ id }: { id: string }) { function onDelete() { const todo = selectTodoById.select(reactStore.state, id); if (todo && !todo.completed) { reactStore.dispatch(deleteTodo(id)); } } return <button onClick={onDelete}>Delete</button>; } ``` ## 7. Common mistakes ### Initializing in an effect after children render ```tsx // ❌ WRONG: children can call selectors before init has run. function AppRoot() { React.useEffect(() => reactStore.init(), []); return <App />; } ``` Initialize at the bootstrap/root owner before rendering selector users, or renderno selector-using children until after explicit initialization has completed. ### Creating stores in components or hooks ```tsx // ❌ WRONG: a new runtime can be created every render/mount. function TodoScreen() { const localStore = new ReactStore({ todos: todosReducer }); const todos = localStore.createSelector((state) => state.todos.ids)(); return <TodoList ids={todos.value} />; } ``` Create/configure the store once in an app module or explicit mount adapter. ### Mixing Store families in one React app path Do not use Svelte `$selector` syntax, Svelte readables, `+layout.svelte`, Svelte context/`onDestroy`, `Store` from `@augmentcode/ag-redux-toolkit/svelte-store`, `StreamingStore`, or Kefir observables in this React app path. ## 8. See also - `react/store/SKILL.md` — `ReactStore` import, lifecycle, and `getSignalState()`. - `react/selector-lifecycle/SKILL.md` — selector call modes across components,handlers, tests, composition, explicit binding, and sagas. - `react/selectors/SKILL.md` — selector authoring for Preact React signals. - `../setup/SKILL.md` — first-time Store-family selection and setup.