Scalable Folder Structure for React and Next.js with React Query

🧱 Scalable Folder Structure for React / Next.js Projects using React Query

In modern frontend development, maintaining a clean, scalable project structure is key — especially when working with tools like React Query for data fetching. Whether you're building with React or Next.js, this folder structure is designed to be flexible, efficient, and easy to maintain.

This structure focuses on API separation, React Query integration, and UI modularity, and works seamlessly in both React and Next.js environments.

🗂️ Folder Overview

• src/ Root source folder to encapsulate all application logic.
• api/ Contains API services, organized by resource. Each file exports reusable functions for data fetching and mutations (used with React Query).
• hooks/ Custom React hooks, including React Query wrappers (e.g., useGetUser, useCreatePost, etc.).
• components/ Reusable UI components (e.g., Button, Modal). Structure supports colocated styles and tests.
• features/ Contains domain-specific logic — usually combines pages, components, hooks, and queries for a single feature/module.
• pages/ (Next.js only) For route-based pages if using Next.js (omit if using plain React with something like React Router).
• store/ Global state management (if any), e.g., Zustand, Jotai, or Context API.
• types/ Centralized location for TypeScript types and interfaces.
• utils/ Shared utility functions and helpers.
• lib/ Any setup or initialization code, such as Axios instance or React Query client setup.

📁 Sample Folder Structure

my-app/
└── src/
    ├── api/
    │   ├── auth.ts
    │   └── posts.ts
    │
    ├── hooks/
    │   ├── useLogin.ts
    │   └── usePosts.ts
    │
    ├── components/
    │   ├── Button/
    │   │   ├── Button.tsx
    │   │   └── Button.module.css
    │   └── Loader.tsx
    │
    ├── features/
    │   ├── auth/
    │   │   ├── LoginForm.tsx
    │   │   ├── useLogin.ts
    │   │   └── api.ts
    │   └── posts/
    │       ├── PostList.tsx
    │       ├── usePosts.ts
    │       └── api.ts
    │
    ├── pages/              # Only for Next.js
    │   ├── index.tsx
    │   └── posts.tsx
    │
    ├── store/
    │   └── userStore.ts
    │
    ├── types/
    │   ├── post.ts
    │   └── user.ts
    │
    ├── utils/
    │   └── formatDate.ts
    │
    └── lib/
        ├── axios.ts
        └── reactQueryClient.ts

✅ Why This Structure?

• Feature-first: Encourages modularization per feature/domain.
• React Query friendly: Separates API logic from hooks and UI.
• Flexible: Easily adapts to both React and Next.js environments.
• Testable & Maintainable: Clear separation of concerns across features and infrastructure.