r/reactjs • u/CaptainZiboo • 6d ago
Discussion How do you structure feature-based React apps with Zustand, TanStack Query, providers, and business logic?
Hey everyone! π
I'm trying to establish a clean, reusable feature-based architecture for React/TypeScript apps, especially when using Zustand + TanStack Query.
I'm working on a visual editor that fetches documents from an API, initializes a Zustand editing session, and will eventually handle canvas state, selection, history, saving, etc.
I'm considering this structure:
features/editor/
βββ components/
βββ hooks/
βββ store/
β βββ editor-store.ts
β βββ editor-store-provider.tsx
β βββ slices/
β βββ document-slice.ts
β βββ selection-slice.ts
β βββ history-slice.ts
βββ queries/
βββ domain/ ?
βββ utils/ ?
βββ lib/ ?
βββ services/ ?I'd love to know how you handle a few things in production:
API / queries: Where do raw API functions go? Do you separate them from TanStack Query options/hooks? Do you organize queries by feature or shared domain?
Zustand: Do you keep providers alongside stores? When do you introduce slices vs multiple stores?
Business/domain logic vs utilities: This is probably what I'm most unsure about. Where do you put pure functions containing actual application logic, independently of React, Zustand or API calls? For example: Would a
domain/directory make sense here? For example,domain/geometry.tsfor canvas calculations,domain/document.tsfor document manipulation, etc. Or would you simply useutils/,lib/orservices/? How do you distinguish business/domain logic from generic utility functions? Is a dedicateddomain/folder a useful convention, or does it introduce unnecessary complexity?Formatting an aspect ratio.
Calculating canvas geometry, scaling or snapping.
Validating editor-specific constraints.
Transforming or manipulating document data.
Shared code: When do you move something out of a feature into a shared location? Do you prefer shared domain modules or global utilities?
Server vs local state: Would you fetch with TanStack Query, initialize Zustand from the result, then keep local edits separate from the query cache? How do you avoid overwriting unsaved changes on refetch?
I'm not looking for a strict architecture or lots of abstractions, just practical conventions that stay maintainable as projects grow.
If you have real-world folder structures or examples, I'd love to see them. Thanks! π
1
u/GeekyAntsBFSI 6d ago
A practical starting point:
features/editor/
api/documents.ts
queries/document-options.ts
store/editor-store.ts
store/editor-provider.tsx
domain/geometry.ts
domain/document.ts
components/domain/Β holds pure editor rules;Β utils/Β holds generic helpers. Keep providers beside stores, add slices when needed, and share code once another feature needs it.
TanStack Query owns server data; Zustand owns the editing draft. Initialize once per document session. Refetches should flag newer versions, never overwrite unsaved edits.
1
u/CaptainZiboo 6d ago
So the main logic must go into /domain ? how about /api and /queries, what would be the difference / purpose of those 2 folders?
1
1
u/rsajdok 3d ago
There is no better example: https://martinfowler.com/articles/modularizing-react-apps.html
2
1
u/DVR_Design 6d ago
For the unsaved changes part, I'd treat the query cache as the last saved snapshot and keep the Zustand session as a separate draft. Initialize the store once per document id (key the provider on the id), and on refetch only rehydrate if the draft isn't dirty, otherwise hold the new server version aside and show a "this changed on the server" prompt. Keep a baseVersion or updatedAt in the store so a save can be rejected or merged when the server moved underneath you. Setting a high staleTime and turning off refetchOnWindowFocus for the editor query also removes most surprise refetches. On folders, a domain/ dir for pure stuff like geometry and snapping is worth it mostly because those are the easiest things to unit test without React.
-4
u/Any-Ring6621 6d ago
The AI does it
0
0
u/Mysterious-Law-3416 6d ago
/api inside editor
keep zustand and providers in stores folder
/utils for util funcs, /schemas for zod schemas
/shared inside /features
depends
-1
u/karmatics29 6d ago
I'd keep three layers apart. Raw API functions live in a plain api file per feature, returning typed data with no React. Query options (queryKey plus queryFn) wrap those, and hooks just call useQuery with them.
A domain/ folder is fine if it holds pure functions with no imports from React, Zustand or fetch: geometry, snapping, document transforms, constraint validation. Those are trivial to unit test. Keep utils/ for generic helpers like formatting an aspect ratio string.
For server versus local state, treat the query result as the baseline and initialize the Zustand session once from it, keyed by document id. Set refetchOnWindowFocus to false for that query, or skip syncing while the store has a dirty flag. Compare a server version or updatedAt on save to catch conflicts. Use slices while they share one undo history and selection model, and split stores only when lifecycles differ.
1
u/CaptainZiboo 6d ago
So basically
/domain = logic
/api = pure api requests
/queries = react query wrappers for /api functionsright ?
1
u/Cordes96 5d ago
Not op, but domain folders are always interesting as that means you have domain logic being separated from the component, which in theory could be mostly solved with composition, not even needing to separate out logic into its own folder. And if it needs to be re used then itβll end up being a hook or a generic utility file. I rarely get to the point of using domain folders, tbh, and I have built giant repos with hundreds of features and still rarely get to /domain, but I have always opted for using hooks for most of my containerization of logic, but a /domain folder does work if you want to keep that logic in a isolated way, but Iβd love to see an example of what you plan to put in there.
But for the /api and /queries, that depends on how you want to use React Query.
There was a time when people really opted for putting useQueries inside a wrapper hook, but now the go-to implementation is to build out the QueryOptions as a pure function as they end up being pure JS and then pass that to useQuery either from a wrapper library or from the TanStack Query library itself.
Like const test = useQuery(testQueryOptions);So if you go by this implementation, youβll only need one folder to hold your QueryOptions, but it seems like most people end up using /api.
This would also mean that your mutations would just be react hooks ending up in your /hooks folder
17
u/Cordes96 6d ago edited 6d ago
I separate them out into query keys so that I can re use the query keys across the application without needing to import hooks, and also it allows me to invalidate queries without having to do anything extra beyond importing the query keys across features, which end up in a shared api folder either in a package or in shared/api to avoid cross-feature imports and the hooks stay in the feature.
Also a side note. Query keys don't require react unlike hooks so if you use this in a mono repo you can use the query keys across multiple applications that have different javascript frameworks and still be able to build the same api endpoints.
These stay in features unless used in multiple features; then the required pieces are pulled up into their own reusable store in shared/stores.
My repo is a monorepo, and I build them out into a utility library or put shared utility files in shared, or if they are local, in a feature/utils folder.
Anything that can be built into a feature and then used in composition, I do so thatt way the feature logic is contained, but I can pass components into other components via composition, as I use the top-level routing page to handle my composition of components.
TanStack Query is the source of truth for the server, and Zustand is the source of truth for the UI try to avoid put copies of values from TanStack Query into Zustand; instead, use form libraries if you are editing it, and only put the value to identify the object from the TanStack Query into Zustand if you donβt need to do work on that value inside a store or have it read from some other component in that feature; useState is way easier to use.
These are my opinions, but I have 8 YoE as a software architect/consultant on large frontend monorepos, and these are the most scalable methods I have found without getting super overcomplicated or re inventing the wheel.