← BACK

11 MIN READ

— JOURNAL

How to Structure a React Project in 2026: Feature-Based Architecture

A practical guide to organizing a React codebase by feature: folder layout, shared code, import rules enforced by your linter, and mistakes to avoid.

Comparison of a React project organized by file type and the same project organized by feature, with app, features and shared folders

The most maintainable way to structure a React project in 2026 is by feature. Group everything that belongs to one part of your product (components, hooks, API calls and types) in a single folder, expose only a small public API through an index file, and keep generic code in a separate shared folder. Then let your linter enforce the import rules, so the structure does not erode over time.

This guide shows the folder structure, the rules that keep it healthy, and the linter configuration that enforces them. The example was built with React 19 and Vite, and every lint rule was checked against both valid and invalid imports.

I did not start with this approach. At school, I learned to organize a project by file type. Then I worked in a company, and I saw the limits of that structure: with many more dependencies, a small change in one place causes unwanted side effects in others, and the code becomes extremely rigid. That experience is what made me move to a feature-based structure.

The problem with organizing a React project by file type

Most React projects start like this: a components folder, a hooks folder, an api folder and a types folder. It works well for a small project. Then the project grows, and the problems appear:

What is a feature-based architecture?

In a feature-based architecture, the first level of folders is not the type of file but the part of the product. A feature is an area that a user could name: authentication, tasks, billing, settings. Everything needed for that area lives in its folder: the UI, the logic, the API calls and the types.

The goal is simple: code that changes together stays together. When you work on tasks, you work in features/tasks. When you remove a feature, you delete one folder.

The folder structure

Here is the structure of the example project:

src/
├── app/
│   └── App.tsx                             # composes the features
├── features/
│   ├── auth/
│   │   ├── api/
│   │   │   └── login.ts
│   │   ├── components/
│   │   │   └── LoginButton.tsx
│   │   ├── hooks/
│   │   │   └── useSession.ts
│   │   ├── index.ts                        # public API of the feature
│   │   └── types.ts
│   └── tasks/
│       ├── api/
│       │   └── getTasks.ts
│       ├── components/
│       │   └── TaskList.tsx
│       ├── hooks/
│       │   └── useTasks.ts
│       ├── index.ts                        # public API of the feature
│       └── types.ts
├── shared/
│   ├── components/
│   │   └── Button.tsx
│   └── lib/
│       └── http.ts
└── main.tsx                                # entry point

There are three layers:

The dependency rules

A good structure is not only about folders, it is about which folders may import which. Here are the four rules:

  1. shared imports nothing from features or app.
  2. A feature can import from shared, but never from app.
  3. A feature never imports another feature. If two features must work together, you compose them in app.
  4. app imports a feature only through its index.ts.

Diagram of the allowed import directions between the app, features and shared layers of a React project

Dependencies flow in one direction, from app to features to shared. That is what prevents circular imports, and what makes a feature easy to move or delete: the only place that knows about it is app.

A real example

Let's look at the code. Each feature exposes only what other parts of the app need, through its index.ts. Everything else stays private:

export { TaskList } from "./components/TaskList";
export type { Task } from "./types";

Inside the feature, the layers are simple. The API call uses the shared HTTP client:

import { http } from "@/shared/lib/http";
import type { Task } from "../types";

export const getTasks = () => http<Task[]>("/tasks");

A hook calls the API and manages the loading and error states:

import { useEffect, useState } from "react";
import { getTasks } from "../api/getTasks";
import type { Task } from "../types";

export function useTasks() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    getTasks()
      .then(setTasks)
      .catch(setError)
      .finally(() => setLoading(false));
  }, []);

  return { tasks, loading, error };
}

And the component uses the hook:

import { useTasks } from "../hooks/useTasks";

export function TaskList() {
  const { tasks, loading, error } = useTasks();

  if (loading) return <p>Loading…</p>;
  if (error) return <p role="alert">Could not load tasks.</p>;

  return (
    <ul>
      {tasks.map((task) => (
        <li key={task.id}>{task.title}</li>
      ))}
    </ul>
  );
}

Notice that inside the feature, files import each other with relative paths (../hooks/useTasks). Across layers, we use the @/ alias. This convention makes it easy to tell, at a glance, whether an import stays inside a feature or crosses a boundary.

The app layer composes the features, importing them only through their public API:

import { LoginButton } from "@/features/auth";
import { TaskList } from "@/features/tasks";

export function App() {
  return (
    <main>
      <header>
        <LoginButton />
      </header>
      <TaskList />
    </main>
  );
}

Set up the @/ alias

The @/ alias points to the src folder. In tsconfig.app.json, add a paths entry in compilerOptions:

{
  "compilerOptions": {
    "paths": { "@/*": ["./src/*"] }
  }
}

And in vite.config.ts, tell Vite how to resolve it:

import { fileURLToPath, URL } from "node:url";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) },
  },
});

Enforce the rules with your linter

Rules that only live in a README get broken. The best way to protect the architecture is to make the linter fail when someone breaks it. The core no-restricted-imports rule is enough, with a different set of restrictions for each layer:

import js from "@eslint/js";
import { defineConfig } from "eslint/config";
import tseslint from "typescript-eslint";

const forbid = (patterns) => ({
  "no-restricted-imports": ["error", { patterns }],
});

export default defineConfig(
  { ignores: ["dist"] },
  js.configs.recommended,
  tseslint.configs.recommended,

  // shared: generic code, depends on nothing in the app
  {
    files: ["src/shared/**/*.{ts,tsx}"],
    rules: forbid([
      {
        group: ["@/features/**", "@/app/**"],
        message: "Shared code cannot depend on features or on the app layer.",
      },
    ]),
  },

  // features: can use shared, but not the app layer or other features
  {
    files: ["src/features/**/*.{ts,tsx}"],
    rules: forbid([
      {
        group: ["@/app/**"],
        message: "A feature cannot import from the app layer.",
      },
      {
        group: ["@/features/**"],
        message: "A feature cannot import another feature. Compose features in the app layer.",
      },
    ]),
  },

  // app: can use features, but only through their public API (index.ts)
  {
    files: ["src/app/**/*.{ts,tsx}"],
    rules: forbid([
      {
        group: ["@/features/*/**"],
        message: "Import a feature through its index.ts, not through its internal files.",
      },
    ]),
  },
);

Now, if a feature tries to import another feature, the linter refuses:

src/features/auth/components/BadFeature.tsx
  1:1  error  '@/features/tasks' import is restricted from being used by a pattern. A feature cannot import another feature. Compose features in the app layer  no-restricted-imports

The same happens if app reaches into the internal files of a feature instead of using its public API:

src/app/BadDeep.tsx
  1:1  error  '@/features/tasks/hooks/useTasks' import is restricted from being used by a pattern. Import a feature through its index.ts, not through its internal files  no-restricted-imports

Imports through index.ts, and imports from shared, are accepted without any error. Type-only imports (import type) are checked as well.

Using oxlint instead of ESLint

If your project was created with the current Vite template, it uses oxlint. The same rules work there. Add this overrides section to your .oxlintrc.json:

  "overrides": [
    {
      "files": ["src/shared/**/*.{ts,tsx}"],
      "rules": {
        "no-restricted-imports": ["error", { "patterns": [
          { "group": ["@/features/**", "@/app/**"], "message": "Shared code cannot depend on features or on the app layer." }
        ] }]
      }
    },
    {
      "files": ["src/features/**/*.{ts,tsx}"],
      "rules": {
        "no-restricted-imports": ["error", { "patterns": [
          { "group": ["@/app/**"], "message": "A feature cannot import from the app layer." },
          { "group": ["@/features/**"], "message": "A feature cannot import another feature. Compose features in the app layer." }
        ] }]
      }
    },
    {
      "files": ["src/app/**/*.{ts,tsx}"],
      "rules": {
        "no-restricted-imports": ["error", { "patterns": [
          { "group": ["@/features/*/**"], "message": "Import a feature through its index.ts, not through its internal files." }
        ] }]
      }
    }
  ]

A heads-up for new projects: the Vite template installs TypeScript 7, and at the time of writing (November 2026), typescript-eslint does not list it as a supported version. Installing ESLint with typescript-eslint fails with a peer dependency error. You can either use oxlint, or install typescript@~5.9.

A limit to know about

These rules check the import path as written. A relative import that climbs out of the feature, like ../../tasks/components/TaskList, is not detected. Use the @/ alias whenever an import leaves a feature, and keep relative paths for files inside the same feature. If you want stricter checks, a dedicated plugin such as eslint-plugin-boundaries can enforce layers more precisely.

Where does each file go?

When you are not sure where to put a file, these questions usually settle it:

Start simple

You do not need this structure on day one. A small project with a handful of components is perfectly fine with flat folders. Consider switching when a single change keeps touching many folders, or when components becomes a long list nobody can navigate.

You can also migrate gradually: move one feature at a time into features, and add the lint rules once the structure is in place.

Common mistakes

What about Next.js?

The same idea applies. In the Next.js App Router, the app directory is used for routing, so keep your route files thin: they should only compose features. Put the real logic in src/features, with the same dependency rules.

Conclusion

A feature-based architecture keeps related code together, makes features easy to delete, and gives each part of the project a clear owner. What makes it last is not the folders, it is the rules: one-way dependencies, a public API per feature, and a linter that enforces them.

If you want to see how I organize my own projects, have a look at my projects, or send me an email.