DEV Community: Oleksii Kyrychenko

Feature-Based Architecture in React: A Structure That Scales Without Turning Into Chaos

Oleksii Kyrychenko — Sat, 11 Apr 2026 16:40:30 +0000

TL;DR

The classic components/hooks/utils structure often breaks down as the codebase and team grow
Feature-based architecture organizes code by domain responsibility, not by technical type
Each feature should expose a small public API, while keeping implementation details internal
A lightweight features/core/ layer can hold reusable domain-aware slices shared across features
Full features should stay isolated from sibling features
The key rule is simple: avoid deep imports and keep dependency direction explicit

The Problem With the “Standard” Structure

A lot of React projects start the same way:

src/
  components/
  hooks/
  utils/
  pages/
  store/

At first, it feels natural. But after a few months, especially in a team environment, the structure starts working against you.

The components/ folder becomes a mix of reusable UI primitives, domain-specific widgets, and half-page composites. hooks/ collects everything from generic helpers to business-critical orchestration. utils/ becomes a dumping ground. Refactoring one feature often means touching files spread across five or six unrelated directories.

The real issue is not the folder names themselves. The issue is that the codebase is organized by technical role instead of domain ownership.

That usually creates a few recurring problems:

feature logic is scattered across the tree
boundaries between reusable and domain-specific code become blurry
onboarding gets slower because developers need to learn the whole project structure before changing one feature
hidden dependencies accumulate over time
deleting or isolating a feature becomes risky

A structure like this may be acceptable for a small app or a solo prototype. But once the application grows, it often stops being a source of clarity and starts becoming a source of entropy.

How a Codebase Typically Evolves

It helps to see this as a progression rather than a one-time decision.

Stage 1 — The classic structure starts to crack

Imagine a users domain. In a classic structure, its pieces live like this:

src/
  components/
    UserAvatar.tsx        ← domain UI buried among generic components
    Button.tsx
    Modal.tsx
  hooks/
    useCurrentUser.ts     ← domain hook mixed with generic helpers
    useDebounce.ts
  store/
    userSlice.ts          ← domain state alongside unrelated slices
    cartSlice.ts
  utils/
    formatUserName.ts     ← domain util in a generic dumping ground

At some point, the orders feature needs UserAvatar. Since there is no clear boundary, it imports it directly:

import { UserAvatar } from '@/components/UserAvatar'

That import works today. But now orders is coupled to the internal path of user-related code. If the file moves, or UserAvatar gains a domain-specific dependency — orders breaks too.

Stage 2 — Extract the first feature

The fix is to move everything belonging to users into one place:

features/
└── users/
    ├── components/
    │   └── UserAvatar/
    ├── hooks/
    │   └── useCurrentUser/
    ├── store/
    ├── types/
    └── index.ts          ← exports only what consumers should use

Now orders imports through the public API:

import { UserAvatar } from '@/features/users'

The internal layout of users is now free to change without breaking anything outside.

Stage 3 — Cross-feature reuse forces a new layer

After a few more features are migrated, a new problem appears.

UserAvatar is now also needed in catalog. And PermissionGate — originally written inside orders — is needed in both catalog and users.

The naive fix would be direct sibling imports:

// Inside catalog — avoid this
import { UserAvatar } from '@/features/users'
import { PermissionGate } from '@/features/orders'

That creates hidden coupling between features. catalog now depends on orders for a UI component. The dependency graph starts getting tangled.

The right move is to extract these shared domain pieces into features/core/:

features/
  core/
    userAvatar/
      components/
      index.ts
    permissions/
      components/
      hooks/
      index.ts
  users/
  catalog/
  orders/

Now catalog and orders import from features/core/ instead:

import { UserAvatar } from '@/features/core/userAvatar'
import { PermissionGate } from '@/features/core/permissions'

This is the key insight: features/core/ is not a layer you design on day one. It emerges naturally once real cross-feature reuse appears and you want to avoid sibling feature dependencies.

The Core Idea

The principle behind feature-based architecture is straightforward:

Group code by domain, not by technical role.

That means everything related to a feature lives together:

UI
hooks
state
types
API calls
feature-specific helpers

Instead of asking:

Is this a hook or a component?

you start asking:

Which domain does this belong to?

That shift changes the way the project evolves. A feature stops being spread across the codebase and becomes a coherent slice with its own internal structure and boundaries.

A Practical Top-Level Structure

A reasonable React application often ends up with five top-level layers.

The dependency flow always moves downward — layers can only import from layers below them, never above:

flowchart TD
    App["app/"] --> Pages["pages/"]
    Pages --> Features["features/"]
    Features -.-> Core["features/core/"]
    Features --> Shared["shared/"]
    Core --> Shared

Here is how it maps to folders:

src/
├── app/
├── pages/
├── features/
│   ├── core/
│   └── ...
└── shared/

`app/`

Application bootstrap and composition only:

providers
router setup
theme setup
global styles
app-level initialization

This layer should stay infrastructural. It is not the right place for domain logic.

`pages/`

Route-level composition.

This layer acts as a bridge between the router and the feature modules. Its responsibility is to orchestrate multiple features and prepare page-level components that are attached to the routing layer.

Pages should usually stay thin. They may work with route params, page layout, and feature composition, but they should not become a second business layer containing domain logic that belongs in features/.

A typical page can stay this simple:

import { useParams } from 'react-router-dom'
import { PageLayout } from '@/shared/ui/PageLayout'
import { ProductDetails } from '@/features/catalog'
import { Recommendations } from '@/features/core/recommendations'

export function ProductPage() {
  const { id } = useParams()

  return (
    <PageLayout>
      <ProductDetails productId={id} />
      <Recommendations context="product" referenceId={id} />
    </PageLayout>
  )
}

`features/`

The main domain layer.

This is where business capabilities live:

auth
orders
catalog
profile
reports
notifications

Each feature owns its own logic and internal implementation details.

`features/core/`

Not everything belongs in shared/, and not everything should live inside a single feature.

features/core/ is a lightweight domain-oriented layer for reusable business slices that are too specific for shared/, but still broad enough to be used across multiple features.

If your team dislikes the name core, that is fine. Names like domain-shared/ or common-domain/ can express the same idea. The important part is the rule behind the layer, not the label.

Typical examples might include:

domain-aware UI fragments
permission-related building blocks
reusable business components
small domain hooks or selectors
common feature contracts and lightweight models

This layer must stay lightweight. It should not contain page orchestration, route wiring, or dependencies on full feature implementations.

`shared/`

Cross-cutting building blocks with no domain ownership:

design-system primitives
API client
low-level utilities
generic hooks
global types

A good rule of thumb: if the code starts knowing too much about a business domain, it probably does not belong in shared/.

Why `features/core/` Exists

By this point, the pattern should be familiar: once a domain-aware module needs to be reused by multiple features, but is still too business-specific for shared/, a separate cross-feature layer becomes useful.

That is the role of features/core/: a controlled dependency boundary for reusable business slices that should not stay inside one concrete feature, but should also not leak into shared/.

What a Feature Looks Like

Inside a feature, you can still organize code by role — but only inside that feature boundary.

features/
└── users/
    ├── components/
    ├── containers/
    ├── hooks/
    ├── store/
    ├── types/
    └── index.ts

That gives you two benefits at once:

the feature remains self-contained
the code inside the feature is still easy to navigate

A common interpretation might look like this:

containers/ — orchestration, data loading, state wiring, side effects
components/ — presentational UI with explicit props
hooks/ — feature-level logic and derived behavior
store/ — local feature state or query keys
types/ — feature-owned contracts
index.ts — public API of the feature

This is not the only valid internal layout, but it is a practical one because it keeps the feature cohesive without flattening everything into one giant folder.

Public API Matters More Than Folder Names

The most important part of this architecture is not whether you use containers/ or components/.

It is this:

A feature should expose a small, intentional public surface.

That is what index.ts is for.

Instead of importing internals directly:

import { UserAvatar } from '@/features/users/components/UserAvatar/UserAvatar'

you import through the feature’s public API:

import { UserAvatar } from '@/features/users'

This gives you a real boundary.

It means:

consumers do not depend on internal file layout
internals can be refactored more safely
the feature communicates what is public and what is private
accidental coupling becomes easier to spot

The goal is not “barrel files everywhere” as a stylistic preference.

The goal is to define module boundaries.

Example Structure

Here is a realistic example:

src/
├── app/
│   ├── App.tsx
│   ├── Router.tsx
│   └── providers/
│       ├── QueryProvider.tsx
│       ├── ThemeProvider.tsx
│       └── StoreProvider.tsx
│
├── pages/
│   ├── catalog/
│   │   └── CatalogPage.tsx
│   ├── product/
│   │   └── ProductPage.tsx
│   └── cart/
│       └── CartPage.tsx
│
├── features/
│   ├── core/
│   │   ├── permissions/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── types/
│   │   │   └── index.ts
│   │   ├── statusBadge/
│   │   │   ├── components/
│   │   │   ├── types/
│   │   │   └── index.ts
│   │   ├── contracts/
│   │   │   ├── types/
│   │   │   └── index.ts
│   │   └── index.ts
│   │
│   ├── users/
│   │   ├── components/
│   │   │   └── UserMenu/
│   │   ├── containers/
│   │   │   └── UserProfile/
│   │   ├── hooks/
│   │   │   └── useCurrentUser/
│   │   ├── types/
│   │   ├── store/
│   │   └── index.ts
│   │
│   ├── catalog/
│   │   ├── components/
│   │   ├── containers/
│   │   ├── hooks/
│   │   ├── types/
│   │   └── index.ts
│   │
│   └── orders/
│       ├── shared/
│       ├── checkout/
│       ├── payment/
│       ├── history/
│       └── index.ts
│
└── shared/
    ├── api/
    ├── config/
    ├── lib/
    ├── types/
    └── ui/

The key point is not the exact naming. The key point is that orders, users, and catalog are treated as domain slices, not as scattered file fragments, while features/core/ holds reusable domain-aware pieces that are safe to share.

Dependency Rules Are What Make This Work

A feature-based structure only scales if dependency direction stays disciplined.

A useful mental model is this:

components should not know about feature orchestration
hooks should not import UI
types should stay lightweight and dependency-poor
cross-feature imports should go through public APIs or features/core/
shared/ should not absorb domain code

Within a feature, a container importing hooks and components is fine:

import { useOrderSummary } from '../hooks'
import { OrderSummaryView } from '../components'
import type { Order } from '../types'

But a component reaching into store, router, or data-fetching logic is often a sign that the layer boundary is getting blurry.

That said, “components must never use hooks” is too absolute.

A presentational component may still reasonably use UI-level hooks like:

useId
useMemo
useRef
measurement hooks
accessibility hooks

A better rule is:

Components should avoid domain side effects, data loading, store access, and cross-feature orchestration.

That keeps the architecture pragmatic instead of dogmatic.

These internal dependency rules are not meant to be absolute laws. They are a practical baseline that teams can adapt depending on the complexity of their UI, state, and data flow model.

Isolating Features From Each Other

One of the most important architectural rules is this:

Full feature modules should not know about sibling features.

In practice, that means:

features/orders/ should not import from features/catalog/
features/catalog/ should not import from features/users/
features/users/ should not import from features/orders/

Direct feature-to-feature dependencies create hidden coupling and make the import graph harder to control.

This rule applies to sibling top-level features. Subfeatures inside one bounded feature, such as features/orders/checkout and features/orders/payment, are a different case because they still belong to the same domain slice.

If some reusable domain logic or UI must be shared across multiple features, it should move into features/core/, not into a sibling feature.

That gives you a cleaner dependency direction:

features/xxx may import from shared/
features/xxx may import from features/core/
features/core/* may import from shared/
features/core/* must not depend on full features
features/xxx must not import sibling features directly

In other words, full features stay isolated, and cross-feature reuse goes through a lightweight core domain layer.

Guardrails for Keeping `features/core/` Clean

This is the most sensitive part of the model.

If left unmanaged, features/core/ can easily turn into a second shared/ or a new dumping ground for everything that feels “kind of reusable.”

That is exactly what should be avoided.

A few guardrails help keep the layer healthy:

only move code into features/core/ when it is genuinely reusable across multiple features
keep it lightweight and domain-aware, but not orchestration-heavy
do not place page assembly, route wiring, or full feature flows there
do not let features/core/ depend on concrete feature implementations
if a module still carries too much feature-specific behavior, keep it inside the feature

A useful test is this:

If a module cannot be reused by at least two features without dragging feature-specific orchestration with it, it probably does not belong in features/core/.

This layer should solve cross-feature reuse, not hide poor boundaries.

For example, a price formatter that only makes sense inside catalog should usually stay in features/catalog/, even if another team is tempted to reuse it once. A single reuse request is not enough reason to turn a feature detail into a cross-feature dependency.

In practice, this layer survives only when teams protect it with clear ownership and strict code review. Without that discipline, features/core/ can degrade into an unstructured catch-all faster than almost any other part of the codebase.

Inside features/core/, it is perfectly fine to reuse the same internal folder anatomy as in regular features, such as components/, hooks/, store, or types.

The important distinction is that core/ should not behave like one large feature-level container. Instead, it should consist of small, focused, reusable domain slices, each with its own local structure and public API.

For example, this is usually a good direction:

features/
  core/
    permissions/
      components/
      hooks/
      types/
      index.ts
    statusBadge/
      components/
      types/
      index.ts
    contracts/
      types/
      index.ts

This keeps core/ modular and explicit. The problem is not repeating folder names like components/ or hooks/. The real risk is turning core/ into a monolithic catch-all such as core/components, core/hooks, or core/types filled with unrelated code.

Large Features and Subfeatures

Not every feature needs subfeatures.

In fact, most features should start flat.

But once a feature becomes large enough to contain several distinct areas, splitting it into subfeatures helps keep the import graph clearer.

For example:

features/
└── orders/
    ├── shared/
    ├── checkout/
    ├── payment/
    ├── history/
    └── index.ts

This is useful when those areas:

have different flows
own different UI and hooks
evolve independently
share some internal primitives, but not everything

A structure like this can reduce the chance of circular dependencies and boundary leakage, especially if the root feature API stays small and the subfeatures do not import each other’s internals.

I would avoid claiming that this makes cycles “physically impossible.” It does not. But it does make the dependency graph easier to reason about and significantly reduces the likelihood of accidental coupling when paired with import restrictions.

Import Rules That Age Well

A practical rule set looks like this:

Good

import { UserAvatar } from '@/features/users'
import { CheckoutStepper } from '@/features/orders/checkout'
import { PermissionGate } from '@/features/core/permissions'
import { Button } from '@/shared/ui/Button'

Avoid

import { UserAvatar } from '@/features/users/components/UserAvatar/UserAvatar'
import { PaymentBadge } from '@/features/orders/payment/components/PaymentBadge'
import { ProductCard } from '@/features/catalog/components/ProductCard'

Why this matters:

internal layout can change without breaking consumers
refactors stay local
ownership is clearer
dependency review becomes easier in PRs

This is one of the rare rules that is both simple and genuinely high-value:

Do not deep-import into another feature, and do not depend on sibling features directly.

What This Architecture Improves in Practice

When implemented with discipline, feature-based architecture tends to improve several day-to-day problems.

1. Locality

Everything related to one domain capability lives in one place.

A developer working on checkout should not need to jump across six top-level folders to understand one flow.

2. Encapsulation

Feature internals stay private unless intentionally exported.

That makes refactors less fragile.

3. Onboarding

New developers can reason about one domain slice at a time instead of learning the entire technical tree upfront.

4. PR Scope

Changes are more likely to stay inside one bounded area.

That makes reviews easier and safer.

5. Parallel Work

Teams working across different features collide less often when boundaries are real.

6. Safer Cross-Feature Reuse

Reusable business pieces move into features/core/ instead of leaking through sibling feature dependencies.

7. Deletion and Extraction

A well-isolated feature is easier to remove, replace, or extract into a separate package or app section.

Not trivial. Not always one command. But definitely easier than in a scattered structure.

The Trade-Offs

This is the part many architecture articles skip.

Feature-based architecture is useful, but it is not free.

More structure upfront

You need to define boundaries deliberately instead of letting the project grow organically.

That requires judgment.

More layers to keep clean

Once features/core/ exists, somebody needs to protect it from becoming a second shared/ dumping ground.

More files

If every small piece gets its own folder, index.ts, types.ts, utils.ts, and so on, the structure can become too granular.

What was meant to improve clarity can become ceremony.

More conventions to enforce

Without lint rules and review discipline, people eventually start bypassing the boundaries:

deep imports
sibling feature dependencies
shared/ becoming a junk drawer
features/core/ becoming an unbounded catch-all

Public APIs require maintenance

Once a feature has an explicit public surface, somebody has to own it.

That is a good thing, but it still has a cost.

Not every project needs it

For a small product, internal tool, or early MVP, this architecture may be more formal than the project actually needs.

So the right question is not:

Is feature-based architecture good?

The right question is:

Is the complexity of this codebase high enough to justify stronger boundaries?

When This Approach Fits Best

This architecture tends to work especially well when:

the app has multiple business domains
several developers work in parallel
the project will live for a long time
the team cares about ownership and maintainability
feature boundaries are more important than technical grouping

It is particularly effective in products where business workflows keep growing:

admin platforms
dashboards
e-commerce apps
SaaS products
enterprise frontends
large internal tools

When I Would Not Reach for It First

I would be more cautious in cases like:

a small solo project
an MVP still searching for product shape
a tiny marketing app
a codebase with very little domain depth
a design-system-heavy app where feature boundaries are minimal

In those cases, a lighter structure may be enough.

Architecture should reduce friction, not introduce it prematurely.

Migrating an Existing Project

You do not need a big-bang rewrite.

A gradual migration is usually the better choice.

Step 1 — Define aliases

Set up imports like:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/features/*": ["src/features/*"],
      "@/shared/*": ["src/shared/*"],
      "@/pages/*": ["src/pages/*"]
    }
  }
}

This makes future boundaries clearer from the start.

Step 2 — Create `shared/`

Move only truly generic pieces first:

UI primitives
API client
cross-app utilities
generic hooks

This is usually the safest extraction.

Step 3 — Migrate one small feature

Choose an isolated domain and move it completely.

Do not redesign the whole project at once.

Step 4 — Add public APIs

Introduce index.ts at the feature boundary and stop deep imports from outside.

Step 5 — Introduce `features/core/` when cross-feature reuse appears

At this point, if two or more features need the same domain piece, move it to features/core/ rather than creating a sibling feature dependency.

Extract only those business-oriented pieces that are lightweight, reusable, and needed across multiple features.

Do not move orchestration there. Do not move full feature flows there.

Step 6 — Enforce rules

Use ESLint to restrict cross-feature deep imports and sibling feature dependencies.

Tools like eslint-plugin-boundaries or linters from the Feature-Sliced Design ecosystem are excellent choices for this. You can configure them to strictly forbid a feature from importing another sibling feature, or to block deep paths.

Without enforcement, the architecture becomes a suggestion instead of a boundary.

Rules Worth Keeping

If I had to reduce the whole approach to a few durable rules, I would keep these:

1. Organize by domain ownership

A feature should own its UI, hooks, state, types, and logic.

2. Keep public APIs small

Do not expose everything by default.

3. Avoid deep imports across feature boundaries

Import from the feature, not from its internals.

4. Keep full features isolated

Feature modules should not know about sibling features.

5. Use `features/core/` for lightweight reusable domain slices

If cross-feature reuse is needed, route it through a controlled core domain layer rather than direct feature-to-feature imports.

6. Keep `shared/` free from business logic

Infrastructure belongs in shared/. Domain behavior belongs in features/ or features/core/.

7. Start simple, split later

Do not introduce subfeatures too early. Add them when the feature actually becomes too large or too mixed.

One Important Caveat

Folder structure alone does not solve architecture.

A codebase can still become chaotic even with beautiful feature folders if:

ownership is unclear
review discipline is weak
shared boundaries are ignored
abstractions are introduced too early
business logic leaks through “helper” files

The structure helps, but the real value comes from the dependency discipline behind it.

That is what makes the difference between a folder convention and an actual architecture.

Relation to Feature-Sliced Design (FSD)

If this structure feels familiar, it is because it shares its philosophy with Feature-Sliced Design (FSD).

What it keeps from FSD:

explicit boundaries between slices
public APIs instead of deep imports
strong dependency direction

What it simplifies:

fewer top-level layers to explain
no separate entities and widgets layers
a more pragmatic path for teams that want the benefits without the full model

In that sense, this is not an alternative to FSD as much as a lighter interpretation of the same core instinct: make boundaries visible, and make dependency direction intentional.

Conclusion

Feature-based architecture is not a magic formula, and it is not the only valid way to structure a React codebase.

But for growing applications, it solves a real problem: it aligns the codebase with the shape of the business domain and makes dependency direction more explicit.

That gives you something more valuable than neat folders.

It gives you:

clearer ownership
safer refactoring
smaller dependency surfaces
better onboarding
less structural drift over time
more controlled cross-feature reuse

The goal is not to create the “perfect” folder tree.

The goal is to make the codebase easier to understand, change, and scale.

If your current structure is already making feature work feel scattered, this approach is worth serious consideration.

Start with one feature. Keep the boundaries real. Let the structure prove itself in practice.

Acknowledgment

I’d like to thank my team and my team lead for the inspiration behind this article. Many of the ideas in it were shaped through engineering discussions, collaboration, and practical experience.

Discussion
How do you handle feature boundaries in React projects? Do you prefer a flatter feature model, or do you introduce a lightweight core domain layer for safe cross-feature reuse?

Stop Fighting Zustand Context: Practical Store Scoping Patterns for React

Oleksii Kyrychenko — Sun, 29 Mar 2026 17:04:16 +0000

Zustand is one of the rare state management libraries that feels good almost immediately. It is small, fast, and does not try to force a framework-sized architecture onto your app.

That simplicity is exactly why many teams adopt it quickly.

Then the app grows, and a different problem shows up: scoped state.

What happens when your app needs multiple, isolated instances of the same store? Imagine a dashboard where each complex "widget" needs its own independent state or a multi-step "wizard" where simultaneous tabs shouldn't overwrite each other's data.

The official Zustand documentation recommends using React Context for this, but doing it manually is a grind. You have to:

Create a React Context.
Create a factory function for the store instance.
Build a wrapper Provider component.
Manually rebuild strongly-typed selector hooks (useStore, useStoreApi) for consumers.
Pepper your codebase with useShallow to prevent unnecessary re-renders when returning objects or arrays.

At that point, plain Zustand is still capable, but the implementation starts getting repetitive.

To reduce that boilerplate, I built @okyrychenko-dev/react-zustand-toolkit.

It gives you a few composable helpers around Zustand:

generated context providers
shallow-first selectors by default
"resolved" hooks that can read from either a scoped or global store
a small set of React 19 utilities

The goal of this article is not to oversell that toolkit. It is to show the real architectural cases where it helps, where it does not, and how its three main factory functions map to actual React state ownership patterns.

Before We Start: The Real Problem

Zustand itself is not the problem. In many apps, plain Zustand is already enough:

one global store
a few focused selectors
occasional middleware
no need for isolated store instances

The pain starts when your architecture stops being purely global.

That usually happens in one of these situations:

you render the same complex widget multiple times and each instance needs separate state
you build reusable modules that should work standalone and also inside a larger application
you want most of the app to read from one global store, but a subtree should temporarily override it
you are tired of repeating provider + context + hook wiring for every isolated Zustand use case

That is the exact gap this toolkit is trying to cover.

So while this article shows the library API, the more important takeaway is architectural:

use a plain global store when isolation is not needed
use scoped providers when identity and lifetime matter per subtree
use resolved hooks when consumers should not care where the state comes from

With that framing in place, the API makes much more sense.

1. The Global Singleton: `createShallowStore`

Let’s start with the simplest layer.

If you are just building a standard global store, the main reason to use this layer is shallow-first selectors.

In standard Zustand, if your selector returns a new object or array, your component will re-render every single time the store updates, even if the selected values haven't changed. To fix this, you have to manually wrap your selectors:

// ❌ Standard Zustand requires boilerplate for shallow picks
import { useShallow } from 'zustand/react/shallow'

const { id, name } = useUserStore(
  useShallow((state) => ({ id: state.id, name: state.name }))
)

With createShallowStore, your generated hooks use zustand/shallow by default. You can pick objects and arrays freely without the boilerplate:

import { createShallowStore } from "@okyrychenko-dev/react-zustand-toolkit";

interface SessionStore {
  token: string | null;
  user: { name: string; role: string } | null;
  login: (token: string, user: { name: string; role: string }) => void;
}

const { useStore, useStorePlain, useStoreApi } = createShallowStore<SessionStore>((set) => ({
  token: null,
  user: null,
  login: (token, user) => set({ token, user }),
}));

// ✅ Object picks use shallow comparison by default.
function ProfileInfo() {
  const { token, user } = useStore((state) => ({
    token: state.token,
    user: state.user
  }));

  return <div>{user?.name}</div>;
}

If you ever need standard, strict-equality behavior, the toolkit always provides explicit useStorePlain alternatives.

Why this matters in practice

The shallow-first approach is especially useful when components naturally want to read small object bundles:

const { isLoading, error, reload } = useStore((state) => ({
  isLoading: state.isLoading,
  error: state.error,
  reload: state.reload,
}));

In plain Zustand, patterns like this often push teams into one of two habits:

wrapping selectors in useShallow
splitting every field into its own selector call

Both work. They are just noisy when repeated across a large codebase.

This helper does not replace selector discipline. It simply makes the common "pick a few fields" case less repetitive.

What it does not do

It is still important to be precise about the limits:

it does not make every selector free
it does not replace good store design
it does not solve deep comparison problems
it does not remove the need to think about derived data and subscription granularity

It mainly improves the ergonomics of shallow object and array picks.

2. Isolated Store Contexts: `createStoreProvider`

The next layer is where Zustand usually becomes a little more manual.

When you need true isolation, where every instance of a component must own a separate store, createStoreProvider removes most of the repetitive setup.

It generates the Context, the Provider component, and the typed consumer hooks in a single call.

import { createStoreProvider } from "@okyrychenko-dev/react-zustand-toolkit";

interface WizardStore {
  step: number;
  direction: 'forward' | 'backward';
  next: () => void;
}

// 1. Generate the provider and hooks
export const { 
  Provider: WizardProvider, 
  useContextStore,
  useContextStoreApi 
} = createStoreProvider<WizardStore>((set) => ({
  step: 1,
  direction: 'forward',
  next: () => set((state) => ({ 
    step: state.step + 1, 
    direction: 'forward' 
  })),
}), "Wizard");

// 2. Consume safely within the isolated tree
function WizardControls() {
  const step = useContextStore((state) => state.step);
  const next = useContextStore((state) => state.next);

  return (
    <div>
      <p>Current Step: {step}</p>
      <button onClick={next}>Next Step</button>
    </div>
  );
}

Why provider-scoped Zustand is useful

Context-scoped stores are not just an implementation detail. They model a different ownership pattern.

With a global singleton store:

the store exists once
every consumer shares the same data
state lifetime usually matches the application lifetime

With a provider-scoped store:

each provider instance owns one store
sibling subtrees can hold completely different values
state lifetime follows the mounted subtree

That makes provider-scoped stores a good fit for:

wizards
modals with complex internal state
embeddable widgets
repeated dashboard panels
request or test isolation

Provider Lifecycle Hooks

Sometimes you need to initialize your isolated store with data from outside (like props) before the component renders, or run a side effect right after it mounts.

The generated Provider component supports two lifecycle stages:

onStoreInit: Synchronous initialization during store creation.
onStoreReady: Post-commit side effects.

function WizardShell({ initialStep }: { initialStep: number }) {
  return (
    <WizardProvider
      onStoreInit={(store) => {
        // Initialize the store synchronously before first render
        store.setState({ step: initialStep });
      }}
      onStoreReady={(store) => {
        // Run side effects like analytics tracking after mount
        console.log("Wizard instance mounted at step", store.getState().step);
      }}
    >
      <WizardControls />
    </WizardProvider>
  );
}

That split is small, but useful:

onStoreInit is for deterministic setup before consumers read the store
onStoreReady is for effects that should happen after mount

That is a better mental model than mixing initialization and side effects in the same callback.

3. The Best of Both Worlds: `createStoreToolkit`

This is the layer that makes the package feel more like a toolkit and less like a single helper.

What if you have global state, but certain parts of the UI need to override it locally?

This is where createStoreToolkit becomes useful.

It creates both a global singleton store and an optional context provider. It also gives you resolved hooks such as useResolvedValue and useResolvedStoreApi.

These hooks dynamically check the React Component tree:

Are we inside a Provider for this store? If yes, use the scoped context store.
No Provider found? Fall back to the global singleton store.

Take a look at this Theme example:

import { createStoreToolkit } from "@okyrychenko-dev/react-zustand-toolkit";

interface ThemeStore {
  mode: 'light' | 'dark';
  setMode: (mode: 'light' | 'dark') => void;
}

// Generates both global store AND provider
const themeToolkit = createStoreToolkit<ThemeStore>((set) => ({
  mode: 'light', // Global default
  setMode: (mode) => set({ mode }),
}), { name: "Theme" });

export const { useResolvedValue: useTheme } = themeToolkit;
export const { Provider: ThemeProvider } = themeToolkit.provider;

Now consuming components do not need to care whether they are reading from the global store or a scoped provider instance:

function ThemedCard() {
  const mode = useTheme((state) => state.mode);
  return <div className={`card-${mode}`}>Smart Card</div>;
}

function App() {
  return (
    <div>
      {/* 🌍 1. Uses the global 'light' theme */}
      <ThemedCard /> 

      {/* 🏠 2. Overrides the state to 'dark' for this specific tree ONLY */}
      <ThemeProvider onStoreInit={(store) => store.getState().setMode('dark')}>
        <div className="dark-zone">
          <ThemedCard />
        </div>
      </ThemeProvider>
    </div>
  );
}

This hybrid pattern is useful for reusable UI modules, nested widgets, or apps where most of the UI can share one store, but a subtree sometimes needs an isolated instance.

Why resolved hooks are interesting

This is probably the most opinionated part of the library.

Normally, when a component can run in two modes, you end up with one of these designs:

separate hooks for global and scoped usage
props that inject the store
branching logic scattered across the component tree

Resolved hooks collapse that decision into one place:

inside the matching provider, read the scoped store
outside it, read the global store

That can simplify component APIs a lot, especially in shared UI packages.

A good mental model

Think of createStoreToolkit as:

a normal global Zustand store
plus an optional scoped override mechanism
plus consumer hooks that pick the nearest valid source

That framing is more accurate than thinking of it as "magic context Zustand".

Where to be careful

Resolved hooks are convenient, but they are also a design choice. I would avoid them when:

the distinction between global and local state should be explicit in the component API
debugging would become ambiguous because a component may silently switch data sources
different teams own global and scoped behavior separately

In other words, resolved hooks are best when the fallback behavior is intentional, not surprising.

4. Middleware Without Losing Types

So far the value has been architectural. This section is more about preserving the normal Zustand experience.

Zustand middleware such as Redux DevTools, Persist, or SubscribeWithSelector still belongs in the store creator.

The useful part here is that the toolkit preserves the resulting store API types, so helpers like persist.rehydrate or selector-aware subscribe remain available on useStoreApi.

import { createShallowStore } from "@okyrychenko-dev/react-zustand-toolkit";
import { devtools, persist } from "zustand/middleware";

interface CartStore {
  items: string[];
  addItem: (item: string) => void;
}

// Middleware types are preserved on the store API.
const { useStore, useStoreApi } = createShallowStore<
  CartStore,
  [["zustand/persist", CartStore], ["zustand/devtools", never]]
>(
  persist(
    devtools(
      (set) => ({
        items: [],
        addItem: (item) => set((state) => ({ items: [...state.items, item] })),
      }),
      { name: "GlobalCartStore" }
    ),
    { name: "cart-storage" }
  )
);

// Mutator APIs stay typed.
useStoreApi.persist.rehydrate();
useStoreApi.devtools.cleanUp();

This does not mean the toolkit adds a custom DevTools layer for provider stores. If you want Redux DevTools, apply Zustand middleware in the creator itself. Dynamic provider instances are not auto-connected for you.

This is a subtle point, but an important one.

The library is not trying to compete with Zustand middleware. It is trying to stay out of the way while preserving the resulting types.

That is the right design choice. Middleware remains a Zustand concern, not a toolkit-specific abstraction.

5. Ready for React 19 ⚛️

This part is useful, but it should be read with the right expectations.

React 19 introduces hooks and rendering primitives such as Transitions, Action State, and Optimistic Updates.

@okyrychenko-dev/react-zustand-toolkit includes a few small utilities around those APIs. They are wrappers, not a new state model.

Wrapping Actions in Transitions

If you have an update that may trigger expensive rendering, you can wrap the action in a transition:

import { createTransitionAction } from "@okyrychenko-dev/react-zustand-toolkit";

const incrementInTransition = createTransitionAction(() => {
  // This update runs inside React.startTransition
  counterToolkit.useStoreApi.getState().increment();
});

Action State Adapters

If you want a thin adapter over useActionState for store-related async actions:

import { useActionStateAdapter } from "@okyrychenko-dev/react-zustand-toolkit";

function SaveForm() {
  const [status, submitForm, isPending] = useActionStateAdapter(
    async (payload: FormData) => {
      await myApi.save(payload);
      myStore.getState().markSaved();
      return "saved";
    }, 
    "idle"
  );

  return (
    <form action={submitForm}>
      <button disabled={isPending}>
        {isPending ? "Saving..." : "Save"}
      </button>
      {status === 'saved' && <p>Saved successfully!</p>}
    </form>
  );
}

Optimistic UI Updates

If you want an optimistic layer on top of committed Zustand state:

import { useOptimisticReducer } from "@okyrychenko-dev/react-zustand-toolkit";

function TodoList() {
  const serverTodos = useTodos((state) => state.todos);

  const [optimisticTodos, addOptimisticTodo] = useOptimisticReducer(
    serverTodos,
    (current, nextTodo) => [...current, nextTodo]
  );

  // ... render optimisticTodos instead of serverTodos
}

I would treat these helpers as convenience utilities, not the center of the package.

They are nice because they keep React 19-oriented code close to the same toolkit, but the core value of the library is still:

store scoping
shallow-first selectors
resolved hooks

That is where the architectural leverage really is.

6. Which Factory Should You Reach For?

If you only remember one section from this article, make it this one.

If you are evaluating the library quickly, this is the practical decision tree:

Use `createShallowStore` when:

you want one global singleton store
your main annoyance is repeated useShallow usage
you do not need isolated instances

Use `createStoreProvider` when:

every mounted subtree should own its own store
the state lifetime should end when that subtree unmounts
store isolation should be explicit

Use `createStoreToolkit` when:

you want a global store by default
some subtrees should be able to override it with local instances
your consumers should work in both environments with the same hook API

That separation is one of the better aspects of the package. The API is not trying to force one pattern onto every use case.

Quick Comparison

Factory	Best for	Store lifetime	Main benefit
`createShallowStore`	One global store	App-wide	Shallow-first selectors with low boilerplate
`createStoreProvider`	Isolated subtree state	Per provider instance	Explicit store ownership and lifecycle
`createStoreToolkit`	Mixed global + local override scenarios	Global plus optional scoped instances	Shared consumer API through resolved hooks

7. When You Probably Do Not Need This Library

This section matters because a good abstraction should come with a clear boundary.

It is also worth being explicit about the non-use-cases.

You probably do not need this toolkit if:

your app already works well with a single global Zustand store
you rarely select object or array bundles
you do not use scoped providers at all
you prefer explicit store injection over fallback resolution

There is no benefit in adding an abstraction layer just because it exists.

Good Zustand architecture is still mostly about picking the right ownership model for state. This toolkit simply makes a few of those models easier to implement consistently.

Wrapping Up

The strongest part of react-zustand-toolkit is not that it reinvents Zustand. It does not.

Its value is that it packages a few repeatable patterns into a small API:

generated providers and hooks for isolated store instances
shallow-first selector hooks with explicit plain alternatives
resolved hooks for code that should work both inside and outside a provider
typed passthrough for Zustand middleware
a few optional React 19 wrappers

If those are problems you keep solving by hand, the library is worth a look.

If your app only needs a single global store, plain Zustand may still be enough, and that is completely fine.

But if your real problem is no longer "how do I store state?" and has become "who owns this state, how many instances of it exist, and how should components resolve it?", then this toolkit starts to become much more interesting.

Next Steps

Install it today:

npm install @okyrychenko-dev/react-zustand-toolkit zustand

Check out the full API reference, examples, and source code in the GitHub Repository.

If you have run into the "global store everywhere, until one subtree needs isolation" problem, this is the part of Zustand architecture the toolkit is trying to simplify.

A Cleaner Way to Write Conditional useEffect in React

Oleksii Kyrychenko — Fri, 27 Mar 2026 19:44:45 +0000

If you've built anything in React 18+, you've likely felt the pain of Strict Mode.

You add a simple event listener, fire an analytics event, or connect a WebSocket. You boot up your dev server, and—boom—it fires twice.

React intentionally mounts your component, unmounts it, and remounts it in development to help you catch bugs like stale closures, missed cleanups, and memory leaks. It's an incredibly useful feature, but it can make your development console extremely noisy and trigger unexpected side-effects.

Faced with this, developers often end up doing one of three things:

Disable Strict Mode entirely (and lose out on finding actual bugs).
Add if (!user || !socket) return guard clauses everywhere.
Stuff a useRef(false) flag inside the component to prevent double execution.

What if you could keep Strict Mode on, but express your effect timing declaratively?

Enter @okyrychenko-dev/react-effect-when.

🛑 The Problem with Manual Guards

Let's say you want to connect to a WebSocket, but you need both a userId and an authToken to be ready.

Normally, you'd write something like this:

function RealtimeConnection({ userId, authToken }) {
  useEffect(() => {
    // 1. Guard against empty state or loading moments
    if (!userId || !authToken) {
      return;
    }

    // 2. Do the actual work
    const socket = connectSocket({ userId, token: authToken });

    // 3. Clean up
    return () => socket.close();
  }, [userId, authToken]);
}

This works, but as your app grows, this pattern repeats everywhere. The real trigger condition is hidden inside the effect body. And if you want to reduce duplicate development-time noise for a specific effect, a common workaround is adding a useRef flag alongside those conditions.

✨ The Solution: Declarative Effect Hooks

react-effect-when gives you specialized tools to lift conditions right into the hook's signature. That removes a lot of boilerplate and also provides solid TypeScript narrowing.

Let's take a look at the three main hooks the package provides.

1. `useEffectWhenReady`: For asynchronous data and services

When you are waiting for data, selectors, or services to load, you typically want to ensure none of them are null or undefined.

import { useEffectWhenReady } from "@okyrychenko-dev/react-effect-when";

function Profile({ user, token }) {
  useEffectWhenReady(
    ([readyUser, readyToken]) => {
      // 🚀 TypeScript knows these are non-null and non-undefined!
      trackProfileView(readyUser.id, readyToken);
    },
    // The hook naturally tracks these dependencies:
    [user, token]
  );
}

Why it's better:

No early returns. The effect only fires when all dependencies are non-null and non-undefined.
Built-in TypeScript narrowing. readyUser and readyToken are strictly typed, eliminating the need for user?.id checking inside the effect.

2. `useEffectWhenTruthy`: Perfect for boolean flags and UI states

Sometimes your conditions are simple truthy flags. For instance, you want to show a toast only when a modal actually opens, or connect a UI banner when a user is marked isOnline.

import { useEffectWhenTruthy } from "@okyrychenko-dev/react-effect-when";

function SessionBanner({ token, isOnline }) {
  useEffectWhenTruthy(
    ([readyToken, online]) => {
      connectBannerChannel(readyToken, online);
    },
    [token, isOnline],
    { once: false } // Re-run whenever it becomes truthy again!
  );
}

Here, the effect runs when all dependencies resolve to a truthy value. If isOnline toggles off and then on again, the cleanup runs and the effect reconnects.

3. `useEffectWhen`: Full Control with a Custom Predicate

This is the most flexible option. It works well for cases like analytics events in development or effects that should run only when several conditions match.

import { useEffectWhen } from "@okyrychenko-dev/react-effect-when";

function ProductPage({ productId, isReady }) {
  useEffectWhen(
    ([id]) => {
      analytics.track("product_view", { productId: id });
    },
    [productId, isReady],
    ([, ready]) => ready === true, // Custom predicate
    { once: true }
  );
}

By passing { once: true }, the effect runs once per mount lifecycle after the predicate first matches. That can reduce local Strict Mode noise for effects like analytics, while keeping the condition explicit at the call site.

You can also use custom conditions for re-synchronization. For example, syncing an item list:

useEffectWhen(
  ([itemList]) => {
    syncToServer(itemList);
  },
  [items, isOnline, hasPermission],
  // Custom logic right in the condition signature
  ([itemList, online, permission]) => 
    online === true && permission === true && itemList.length > 0 
);

🔍 Bonus: Debugging with `onSkip`

Ever wonder why an effect isn't firing? Did a socket disconnect, or did the user drop to null? The library provides an onSkip callback for logging the dependency state that failed your predicate.

import { predicates, useEffectWhen } from "@okyrychenko-dev/react-effect-when";

useEffectWhen(
  ([currentUser, currentToken]) => {
    initializeDashboard(currentUser, currentToken);
  },
  [user, token],
  predicates.ready,
  {
    onSkip: ([pendingUser, pendingToken]) => {
      console.debug("Still waiting for dependencies to load:", {
        user: pendingUser,
        token: pendingToken,
      });
    },
  }
);

With this, you can inspect why an effect was skipped when the predicate does not match, instead of manually scattering debug logs through the component.

🚀 The Takeaway

We should not have to fight React's primitives. Ad-hoc useRef(false) flags and if (!data) return conditions get messy fast.

Instead, a small abstraction over useEffect can make intent clearer, reduce repeated guard boilerplate, and preserve the guardrails that React 18 gives us in development.

This is not a replacement for plain useEffect. But if your codebase has a lot of guard-heavy effects, it can be a cleaner way to express them.

If that sounds familiar, give react-effect-when a try.

Try it out:

npm install @okyrychenko-dev/react-effect-when

If you like the approach, drop a ⭐️ on the GitHub repo and let me know what you think in the comments! 👇