Stop Organizing by File Type: The Feature-Based Folder Structure That Scales

1. Introduction — The Folder Structure Problem Nobody Talks About

In the world of modern web development, organizing your project files is more than just a housekeeping task—it's a crucial architectural decision that impacts everything from onboarding new developers to maintaining scalability. The old adage "it works on my machine" extends into "it works in my head," highlighting how personal biases in file organization can lead to larger team inefficiencies. Developers often default to a type-based folder structure, leading to a sprawling mess of directories like `/components`, `/hooks`, `/utils`, and `/actions`, each housing hundreds of files. This setup can initially seem logical, but as projects grow, it becomes a labyrinthine nightmare.

The true cost of maintaining a type-based structure becomes evident when onboarding new developers, who must first understand the project's organization before contributing effectively. Refactoring fear sets in as the codebase expands, with developers hesitant to make changes that could unintentionally affect unrelated parts of the application due to complex dependencies. Dependency spaghetti ensues, where the interconnectedness of modules makes isolated changes nearly impossible.

The solution lies in a feature-based folder structure combined with a one-way data flow, which can significantly reduce these problems. By organizing code around features rather than types, developers can gain clarity and control over the codebase, making it easier to scale and maintain. This approach aligns closely with principles from domain-driven design and encourages a more intuitive organization that mirrors the application's functionality.

2. The Conventional Type-Based Structure (And Why It Breaks Down)

Let's examine a typical folder structure in a Next.js app organized by type. You might have something like this:

```plaintext /src ├── components ├── hooks ├── utils ├── actions ├── reducers ``` At first glance, this seems tidy. However, consider the complexity added when implementing a simple feature like a "delete button." This seemingly trivial addition could require edits across multiple directories: a new component in `/components`, a custom hook in `/hooks`, a utility function in `/utils`, and perhaps an action in `/actions`. Each change forces the developer to traverse multiple folders, breaking concentration and increasing cognitive load.

As features are added, interdependencies grow exponentially. The type-based organization does not naturally enforce boundaries between features, leading to a web of connections that can cause more harm than good. This is a common pain point noted by developers in the community. Kent C. Dodds, in his essay on "Colocation," advocates for organizing code so that related files are kept together, reducing these dependencies and making the codebase more navigable.

The open-source project Bulletproof React by Alan Alickovic provides insights into how this complexity manifests. By analyzing real-world codebases, you see the challenges developers face with type-based structures—where a single change can cascade through many unrelated parts of the code.

3. The Feature-Based Folder Structure — Core Concepts

The feature-based folder structure revolves around the `features/` directory, which serves as the central hub of the application. This approach encourages developers to think in terms of features rather than file types, creating a more cohesive and scalable architecture. The primary layers include:

- `features/<domain>/`: Each domain or feature of the application is self-contained here, encapsulating its components, hooks, and server logic. - `shared/` or `lib/`: This is reserved for truly generic, cross-cutting code that can be reused across multiple features. - `app/` (or `pages/`): This layer acts as a thin glue, primarily for routing and integrating state management.

Here's a breakdown of what a feature folder might look like:

```plaintext /features ├── authentication │ ├── components │ │ └── LoginForm.tsx │ ├── hooks │ │ └── useAuth.ts │ ├── server │ │ └── queries.ts ├── dashboard │ ├── components │ ├── hooks │ ├── server ``` Each feature is encapsulated within its domain, making it easy to manage and scale. By organizing code in this manner, you reduce the cognitive overhead associated with locating and understanding the interactions between files.

Why `features/` is a Game-Changer

The shift to a feature-based structure is a game-changer because it aligns the codebase with the application's real-world functionality. This approach fosters a natural boundary between features, promoting modularity and reducing the risk of unintended side effects when making changes. Developers can focus on implementing and maintaining specific features without worrying about unrelated parts of the codebase.

Moreover, this structure encourages better testing practices. By isolating features, testing becomes more straightforward, with each module having its own test suite that doesn't affect others. This isolation also aids in optimizing build times, as changes to one feature don't necessitate recompiling unrelated parts of the application.

The feature-based approach is particularly advantageous in larger teams, where multiple developers work on different features simultaneously. It reduces the likelihood of merge conflicts and ensures that developers are only working within their specific domain, enhancing productivity and minimizing disruptions.

From Theory to Practice: Implementing a Feature-Based Structure in Next.js

Transitioning from a type-based to a feature-based structure requires careful planning and execution. Start by identifying the main features of your application and create corresponding directories within `features/`. Move relevant components, hooks, and server logic into these directories, ensuring that each feature remains self-contained.

For example, if your application includes user authentication, create a `features/authentication` directory and relocate all related files there. This might include login components, authentication hooks, and any associated server queries or mutations. By doing so, you create a clear boundary for everything related to authentication, simplifying future development and maintenance.

It's essential to continuously evaluate and adjust this structure as your application evolves. New features should be seamlessly integrated into the existing framework, maintaining the clarity and organization that the feature-based approach provides. As noted by Theo Browne in the T3 stack discussions, such an approach not only scales well but also adapts to changing project requirements.

4. Applying Feature-Based Structure to React Native and Expo

Just as with Next.js, React Native and Expo projects can benefit immensely from a feature-based folder structure. These frameworks, designed for building cross-platform mobile applications, often face similar organizational challenges as web projects. By adopting a feature-centric approach, developers can significantly enhance the maintainability and scalability of mobile applications.

In React Native and Expo, the `features/` directory can house platform-specific components and logic, while shared utilities remain in a `shared/` or `lib/` directory. This separation ensures that platform-specific nuances are handled within their respective domains, reducing complexity and improving code clarity.

Consider an application with features like user profiles, notifications, and settings. Each of these can be encapsulated within its feature directory, containing all related components, hooks, and navigation logic. This setup not only simplifies development but also makes it easier to introduce new features or adapt existing ones to different platforms.

Real-World Example: Setting Up a React Native Project

To illustrate, let's look at setting up a React Native project using the feature-based folder structure. A directory layout might resemble the following:

```plaintext /src ├── features │ ├── profiles │ │ ├── components │ │ ├── hooks │ │ ├── navigation │ ├── notifications │ ├── settings ├── shared ├── App.tsx ``` In this example, each feature directory contains the components and logic specific to that feature, with shared resources available across the application. This organization mirrors the application's structure, making it intuitive for developers to locate and modify code as needed.

Implementing this structure in a React Native environment encourages developers to think in terms of features rather than files, aligning closely with Expo's ecosystem, which emphasizes modularity and reusability. By focusing on features, teams can more effectively manage mobile applications, ensuring that they remain robust and adaptable as they grow.

5. Overcoming Challenges and Adopting Best Practices

Transitioning to a feature-based folder structure can present challenges, particularly for teams accustomed to a type-based approach. However, by adopting best practices and leveraging community resources, developers can ease this transition and reap the benefits of a more organized codebase.

One of the primary challenges is overcoming inertia and resistance to change. Developers who have worked extensively with type-based structures may find it difficult to adjust to a new paradigm. To address this, it's crucial to provide clear documentation and examples, highlighting the advantages of the feature-based approach in terms of scalability, maintainability, and ease of collaboration.

Engage with the community and utilize resources from industry leaders. CSS-Tricks, for example, offers insights into organizing large-scale applications, while Kent C. Dodds provides valuable perspectives on colocation and modular design principles. These resources can serve as guides and references, helping teams adapt more effectively.

Best Practices for a Smooth Transition

- **Start Small**: Begin by reorganizing a small part of your application into a feature-based structure. This will allow you to test the new organization without overwhelming the development process. - **Involve the Team**: Engage all team members in the transition. Encourage feedback and suggestions to refine the structure and ensure it meets the team's needs. - **Document Thoroughly**: Maintain comprehensive documentation that outlines the new structure, its benefits, and how to navigate it. This will be invaluable for onboarding new developers and ensuring consistency across the team. - **Leverage Tools**: Utilize tools and libraries that support feature-based organization. Expo and Next.js have robust ecosystems that can facilitate this transition, providing plugins and extensions to streamline development.

By following these best practices, teams can overcome the initial hurdles associated with adopting a feature-based structure. Over time, the benefits will become apparent, with a more organized, scalable, and maintainable codebase that supports rapid development and innovation.

6. Conclusion — Embracing a Scalable Future

The journey from a type-based to a feature-based folder structure marks a significant shift in how developers approach organizing their projects. This change is not merely about rearranging files—it's about adopting a mindset that prioritizes clarity, scalability, and maintainability. For Next.js, React Native, and Expo developers, this approach aligns with modern development practices, enabling teams to build robust applications that can grow and adapt over time.

By embracing a feature-based organization, developers can reduce complexity, enhance collaboration, and improve their ability to respond to changing requirements. As the tech landscape continues to evolve, adopting such scalable solutions becomes increasingly crucial. The insights and resources provided by experts like Kent C. Dodds, Theo Browne, and Alan Alickovic are invaluable in guiding this transformation, offering practical advice and proven strategies to succeed.

The future of application development lies in the ability to manage complexity with elegance and efficiency. By organizing projects around features, developers can unlock the full potential of their codebases, paving the way for innovative, sustainable, and maintainable software solutions.