The Skeleton of React Project Structure
Starting a React project with a solid foundation is like preprationary(prepratory)-work in a kitchen; it makes the actual cooking much smoother. Since we are in 2026, the industry standard has moved toward Vite for speed and TypeScript for reliability.
Here is a blueprint for a professional-grade React skeleton.
We'll use Vite because it’s significantly faster than the deprecated Create React App.
Initialize the project:
Bash
npm create vite@latest my-react-app -- --template react-ts
cd my-react-app
Install Essential Dependencies:
Routing: react-router-dom
State Management: @tanstack/react-query (for server state) or zustand (for global UI state).
Styling: tailwind-css
Icons: lucide-react
A "Feature-Based" structure is generally superior to a "Type-Based" one because it scales better. Instead of putting all components in one giant folder, you group them by what they do.
src/
├── assets/ # Static files (images, svgs, fonts)
├── components/ # Shared global UI components (Buttons, Inputs, Modals)
├── config/ # Environment variables and global constants
├── features/ # Feature-based modules (The "Brain" of the app)
│ ├── auth/ # Everything related to Login/Signup
│ │ ├── api/ # Auth-specific API calls
│ │ ├── components/
│ │ ├── hooks/
│ │ └── types/
│ └── dashboard/ # Everything related to the Dashboard
├── hooks/ # Shared global hooks (useLocalStorage, useWindowSize)
├── layouts/ # Page wrappers (AdminLayout, AuthLayout)
├── pages/ # Route entry points (lazy-loaded)
├── services/ # API clients (Axios instance)
├── store/ # Global state (Zustand/Redux stores)
├── utils/ # Utility functions (formatters, validators)
└── App.tsx # Main provider wrapper
These files live in your root directory and ensure your code is clean and consistent across a team.
| File | Purpose |
vite.config.ts |
Handles build settings and path aliases (e.g., using @/ instead of ../../../). |
.eslintrc.json |
Enforces code quality rules and catches bugs early. |
.prettierrc |
Handles code formatting (tabs, semicolons, quotes). |
tsconfig.json |
Defines how TypeScript compiles your code. |
.env |
Stores sensitive API keys and URLs. |
To visualize how your project will actually run, keep this flow in mind:
Main Entry: main.tsx renders App.tsx.
Providers: App.tsx wraps the app in QueryClientProvider, ThemeProvider, and BrowserRouter.
Routing: routes/index.tsx decides which Page component to show based on the URL.
Feature Logic: The Page uses components from the features/ folder to display data.
Path Aliases: Set up your config so you can import like import { Button } from '@/components' rather than messy relative paths.
Strict Typing: Use TypeScript interfaces for all API responses to prevent "Cannot read property 'x' of undefined" errors.
Lazy Loading: Wrap your main routes in React.lazy() to keep your initial bundle size small and your load times fast.
Setting up Path Aliases and a robust Axios Interceptor are the two "professional- moves" that separate a hobby-project from a scalable production application.
Path aliases allow you to use @/ to refer to your src directory. This prevents "import hell" where you have to type ../../../components.
First, install the supporting types for Node:
Bash
npm install -D @types/node
Update your vite.config.ts:
TypeScript
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';
export default defineConfig({
plugins: [react()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
});
Note: You must also update your
tsconfig.jsonundercompilerOptionsby adding"paths": { "@/*": ["./src/*"] }so TypeScript recognizes the@symbol.
The Interceptor is a central "checkpoint" for every network request. It’s the perfect place to automatically attach Authorization-Tokens or handle 401 Unauthorized errors globally.
Create this in src/services/api-client.ts:
TypeScript
import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
const apiClient: AxiosInstance = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL,
headers: {
'Content-Type': 'application/json',
},
});
// Request Interceptor: Add Authorization header to every request
apiClient.interceptors.request.use(
(config: InternalAxiosRequestConfig) => {
const token = localStorage.getItem('token');
if (token && config.headers) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
},
(error) => Promise.reject(error)
);
// Response Interceptor: Catch global errors (like 401s)
apiClient.interceptors.response.use(
(response) => response,
(error) => {
if (error.response?.status === 401) {
// Logic to logout user or refresh token
console.error('Unauthorized! Redirecting to login...');
}
return Promise.reject(error);
}
);
export default apiClient;
To make the api-client.ts work, you need a .env file in your root folder:
VITE_API_BASE_URL=https://api.yourdomain.com/v1
Cleaner Imports: import { UserProfile } from '@/features/auth' is much easier to read.
Security: Your API token is handled in one file rather than being passed around manually.
Error Handling: If your API ever goes down or a session expires, you handle it in one place (the interceptor) instead of in every component.
To show you how this looks in practice, let's build a Login Feature. This follows the "Feature-Based" architecture we discussed, where all logic, types, and UI for a specific domain live together.
features/auth Folder StructureBy grouping these together, you can literally copy-paste this folder into another project and it will almost work out of the box.
types/index.ts)First, we define what our user and response look like.
api/login.ts)Here we use the apiClient we built earlier. Notice how we use the @ alias.
components/LoginForm.tsx)This is a standard React component using Tailwind CSS for styling.
index.ts)This is the "entry point" for the feature. It exports only what the rest of the app needs to see, keeping everything else private to the folder.
Isolation: If you need to change how Login works, you only look inside the auth folder.
Clean Imports: In your pages/LoginPage.tsx, you just write: import { LoginForm } from '@/features/auth';
Scalability: When you add a billing or profile feature, you just create a new folder following the same pattern.
Since we've already handled the API and the folder structure, Zustand is the perfect final piece. It’s significantly lighter than Redux and doesn't require "Boilerplate" code like Actions or Reducers.
Think of the Store as a "Global Hook" that any component can tap into to get user data.
You can manage the state of a React application in several ways.
Why Zustand?
{x:1, y:2}. You can directly set {y:3}. Zustand will merge the data for you. You don’t have to distribute the old state and update properties like {…state, y:3}.As you may know, Redux is the classic state management library that works with React. It is considered the most popular library for managing React states. Hence, comparing their architectural designs is a fitting component of this article. Look at the architecture below to see how Redux works.
First, you have the front-end user interface, as seen in the architecture above. Action creators ensure that the correct action is triggered for every user request. You can think of an action as an event that describes what happened in the application. It can be like clicking a button or performing a search. Dispatchers will assist in sending those actions to the store. Later on, the reducers will decide how to handle the state. The reducer function changes the state by taking the current state and action object. It will return the new state if required, and the updated state modifications will render the UI.
Take a look at how Zustand works with the architecture as you also have the UI component here. When a change request comes in, it is routed to the store. The store will decide how the state should be changed. The UI will be rendered with the updated changes once the store returns a new state. You don’t see any action creators, dispatchers, or reducers here. Instead, Zustand has a feature that lets you subscribe to state changes. This helps keep your UI in sync with your data, for developers looking for a simple and lightweight state management solution without the complexity of a larger toolkit like Redux, Zustand is a perfect option.
Create this in src/store/auth-store.ts. This store will hold the user's information and provide functions to log in and out.
Now, we update the LoginForm.tsx we built earlier to use this global state. Instead of a manual redirect, we update the store, and the app reacts automatically.
With the store in place, you can create a high-level component to protect your dashboard. If isAuthenticated is false, it kicks the user back to the login page.
Create this in src/components/ProtectedRoute.tsx:
You now have a production-ready skeleton:
Vite + TS: For speed and type safety.
Path Aliases: For clean code.
Feature-Based Folders: For scalability.
Axios Interceptors: For automated security.
Zustand: For effortless global state.
This is where the magic happens. We’ll tie the API, the Store, and the Features into a single routing system that manages access control across your entire application.
src/routes/index.tsx)Instead of cluttering App.tsx, we define a clean routing configuration. We use the ProtectedRoute we created to "wrap" any pages that require a login.
src/App.tsx)In a modern React app, App.tsx acts as the "Provider Layer." It’s where you wrap your app in global configurations like React Query (for caching) and the Router.
Now that the skeleton is complete, here is how a single action flows through your architecture:
User Action: The user clicks "Login" in the LoginForm.
API Call: The feature calls the function in auth/api/login.ts.
Interceptor: The api-client.ts interceptor catches the response and verifies the status.
Store Update: The auth-store.ts (Zustand) updates the global state with the user data.
Re-render: The ProtectedRoute sees that isAuthenticated is now true and automatically allows access to the /dashboard.
You now have a complete, professional React skeleton.
A great README.md is the "Front Door" of your project. It helps teammates get started in minutes and explains the why behind your architectural choices.
Here is a comprehensive README tailored to the skeleton we just built.
A high-performance, scalable React boilerplate built with Vite, TypeScript, Zustand, and Tailwind CSS. Designed for speed, type safety, and maintainable feature-based architecture.
Framework: React 19+
Build Tool: Vite
Language: TypeScript
State Management: Zustand (Global) & React Query (Server)
Routing: React Router 7+
Styling: Tailwind CSS
Icons: Lucide React
This project uses Feature-Based Architecture. Logic is grouped by domain rather than file type.
Create a .env file in the root:
No more relative path hell. Use @ to point to the src directory: import { Button } from '@/components';
Automatic Auth: The Axios interceptor automatically attaches the Bearer token from localStorage to every request.
Protected Routes: Use the <ProtectedRoute /> component in src/routes/index.tsx to guard sensitive pages.
Each folder in src/features is treated as a standalone module. Only export what is necessary via the index.ts file in each feature folder.
Types over Interfaces: Use types for API responses and interfaces for component props.
Lazy Loading: Always lazy load pages in the router to optimize bundle size.
Clean Code: Run npm run lint before committing to ensure code quality.
That completes your full project setup!
Here is a production-ready package.json. This includes the necessary scripts to keep your project clean and the dependencies we've integrated throughout this walkthrough.
Copy the code above into your package.json.
Run npm install to pull in all the libraries.
Verify your tsconfig.json has the path aliases:
You have the skeleton, the muscles (state), and the brain (logic) all set up.
We’ve built a complete, high-performance React ecosystem from the ground up. You’ve moved from a blank folder to a feature-based architecture that is ready for a professional production environment.
Speed: Powered by Vite, giving you near-instant Hot Module Replacement (HMR).
Safety: TypeScript ensures that your API data and component props are predictable and bug-free.
Organization: The Feature-Based structure means your project won't become a "spaghetti-code" mess as it grows.
Global Logic: Zustand manages your UI state, while Axios Interceptors handle your security silently in the background.
Access Control: Protected Routes ensure users only see what they are authorized to see.
Now that the skeleton is standing, you can focus purely on building your product. Every time you need a new functional area (like "Settings" or "Inventory"), simply create a new folder in src/features/ and follow the same pattern: Types -> API -> Components -> Index.
Pro Tip: As your app grows, keep an eye on your bundle size using
npm run build. If it gets heavy, useReact.lazy()for your page imports inroutes/index.tsx.
You're all set! Is there any specific feature or a complex UI component.
Let’s create a React project to show how to manage the states using Zustand. Consider a Library Store application that keeps track of book issues and returns. The steps are listed below.
Create your React application using the below command.
npx create-react-app project_name
Go to the project’s directory and install the zustand dependency to manage the React state.
npm i zustand
Create a bookstore. You can refer to the below code to create bookStore.js file.
import { create } from "zustand";
const bookStore = (set, get) => ({
books: [],
noOfAvailable: 0,
noOfIssued: 0,
addBook: (book) => {
set((state) => ({
books: [...state.books, { ...book, status: "available" }],
noOfAvailable: state.noOfAvailable + 1,
}));
},
issueBook: (id) => {
const books = get().books;
const updatedBooks = books?.map((book) => {
if (book.id === id) {
return {
...book,
status: "issued",
};
} else {
return book;
}
});
set((state) => ({
books: updatedBooks,
noOfAvailable: state.noOfAvailable - 1,
noOfIssued: state.noOfIssued + 1,
}));
},
returnBook: (id) => {
const books = get().books;
const updatedBooks = books?.map((book) => {
if (book.id === id) {
return {
...book,
status: "available",
};
} else {
return book;
}
});
set((state) => ({
books: updatedBooks,
noOfAvailable: state.noOfAvailable + 1,
noOfIssued: state.noOfIssued - 1,
}));
},
reset: () => {
set({
books: [],
noOfAvailable: 0,
noOfIssued: 0,
});
},
});
const useBookStore = create(bookStore);
export default useBookStore;
Zustand store is a hook, which is why useBookStore is the component name. create is the method used to create the store. The store is the sole source of truth that each component shares. The function set is used to modify the state of a variable or object. The function get is used to access the state inside actions.
The state object of the library store in the example contains three fields: books, which contains an array of book details such as id, name, and author. The overall number of books in the library is stored in noOfAvailable, while the total number of books that have been issued to users is stored in noOfIssued. The library store offers four methods: The addBook function will add a new book to the array of books, increasing the number of books that are currently available and setting the state of every newly added book to available. The issueBook function will issue a book to the user. The associated book will now have the status issued. There will be an increase in the count of issues and a drop in the count of available. The returnBook function is used to return the issued book to the library. The status of the returned book will change to available, and the count of issued books will drop while the count of available books will increase. Finally, the reset method clears all of the state fields.
Let’s first create entry point App.js file. Refer to the below code.
//App.js
import { useEffect } from "react";
import BookForm from "./components/BookForm";
import BookList from "./components/BookList";
import useBookStore from "./bookStore";
import "./App.css";
function App() {
const reset = useBookStore((state) => state.reset);
useEffect(() => {
reset();
}, [reset]);
return (
<div className="App">
<h2>My Library Store</h2>
<BookForm />
<BookList />
</div>
);
}
export default App;
There are two components in the App.js file: the BookForm and the BookList. Every time the App component mounts, we also use the reset function to remove any state data.
Create BookForm.js component. Refer to the below code.
//BookForm.js
import { useState } from "react";
import useBookStore from "../bookStore";
function BookFom() {
const addBook = useBookStore((state) => state.addBook);
const [bookDetails, setBookDetails] = useState({});
const handleOnChange = (event) => {
const { name, value } = event.target;
setBookDetails({ ...bookDetails, [name]: value });
};
const handleAddBook = () => {
if (!Object.keys(bookDetails).length)
return alert("Please enter book details!");
addBook(bookDetails);
};
return (
<div className="input-div">
<div className="input-grp">
<label>Book ID</label>
<input type="text" name="id" size={50} onChange={handleOnChange} />
</div>
<div className="input-grp">
<label>Book Name</label>
<input type="text" name="name" size={50} onChange={handleOnChange} />
</div>
<div className="input-grp">
<label>Author</label>
<input type="text" name="author" size={50} onChange={handleOnChange} />
</div>
<button onClick={handleAddBook} className="add-btn">
{" "}
Add{" "}
</button>
</div>
);
}
export default BookFom;
The BookForm component has form fields for entering book details, such as id, name, and author. Additionally, it has an Add button that uses the bookstore’s addBook method to input these book details.
Create BookList.js component. Refer to the below code.
//BookList.js
import { Fragment } from "react";
import useBookStore from "../bookStore";
function BookList() {
const { books, noOfAvailable, noOfIssued, issueBook, returnBook } =
useBookStore((state) => ({
books: state.books,
noOfAvailable: state.noOfAvailable,
noOfIssued: state.noOfIssued,
issueBook: state.issueBook,
returnBook: state.returnBook,
}));
return (
<ul className="book-list">
{!!books?.length && (
<span className="books-count">
<h4>Available: {noOfAvailable}</h4>
<h4>Issued: {noOfIssued}</h4>
</span>
)}
{books?.map((book) => {
return (
<Fragment key={book.id}>
<li className="list-item">
<span className="list-item-book">
<span>{book.id}</span>
<span>{book.name}</span>
<span>{book.author}</span>
</span>
<div className="btn-grp">
<button
onClick={() => issueBook(book.id)}
className={`issue-btn ${
book.status === "issued" ? "disabled" : ""
}`}
disabled={book.status === "issued"}
>
{" "}
Issue{" "}
</button>
<button
onClick={() => returnBook(book.id)}
className={`return-btn ${
book.status === "available" ? "disabled" : ""
}`}
disabled={book.status === "available"}
>
{" "}
Return{" "}
</button>
</div>
</li>
</Fragment>
);
})}
</ul>
);
}
export default BookList;
The BookList component will display all newly added books to the library. It also shows the number of Available and Issued books. Each book record in the list has two buttons: Issue and Return.
There are two books available in the UI above, and Issue button is enabled for each book record. Return buttons are disabled and will enable only for issued books.
When you click the Issue button, the store’s issueBook method is called. The corresponding book ID will be passed and the matching book’s status will set to issued. Then, the associated Issue button is disabled, while the Return button is enabled. You can also see a decrease in the number of Available and an increase in the number of Issued. Please see the screenshot below.
When you click the Return button, the store’s returnBook method is called. The corresponding book ID will be passed and the matching book’s status will set back to available. The associated Return button is disabled, while the Issue button is enabled back. You can also see an increase in the number of Available and a decrease in the number of Issued. Please see the screenshot prior to the above.
Since the Zustand store is a hook, you can use it anywhere. In contrast to Redux or Redux Toolkit, no context provider is required. Simply select your state, and the component will re-render when the state changes. We must give a selector to the useBookStore to get only the desired slice.
We are not done yet! Zustand has a big advantage: Middlewares.
Zustand can be used with en."wikipedia.org/wiki/Middleware" to add more features to your application. The most widely used Zustand middlewares are listed below.
"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd" are used to debug state changes in the application. It can be used with Zustand as well. Make sure you have Redux DevTools installed as a Chrome extension. Use the below code to integrate it.
import { create } from "zustand";
import { devtools } from "zustand/middleware";
const bookStore = (set, get) => ({
books: [],
noOfAvailable: 0,
noOfIssued: 0,
addBook: (book) => {
set((state) => ({
books: [...state.books, { ...book, status: "available" }],
noOfAvailable: state.noOfAvailable + 1,
}));
}
});
const useBookStore = create(devtools(bookStore));
export default useBookStore;
To use devtools, import it from zustand/middleware. Then, wrap your store with devtools using the create method.
Open the Redux DevTools in the web browser and inspect the state.
Persist middleware enables you to persist state using any type of client storage. The store’s data will remain in storage even if you reload the application. Refer to the below code to add this middleware.
import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
const bookStore = (set, get) => ({
books: [],
noOfAvailable: 0,
noOfIssued: 0,
addBook: (book) => {
set((state) => ({
books: [...state.books, { ...book, status: "available" }],
noOfAvailable: state.noOfAvailable + 1,
}));
}
});
const useBookStore = create(
persist(bookStore, {
name: "books",
storage: createJSONStorage(() => sessionStorage),
})
);
export default useBookStore;
Import persist from zustand/middleware. Wrap the store with persist inside the create method. The item in the storage can have a name, but it needs to be unique. Additionally, the type of storage can be specified. sessionStorage is referenced in this code. If nothing is specified, localStorage is the default option.
Open the web browser and look at the session storage to see the saved state.
As we mentioned in this article, state management is critical in React applications. As your application grows, you will have to pick a strong way to manage its state. The Zustand library is an ideal remedy for managing your React state. It is much simpler and has less boilerplate than Redux. You can also explore different state management libraries to find the right one for your application.