How To Create Public Interfaces for React Modules with index.js Files

By using an index.js file in the root of each folder to re-export a subset of files, you can effectively create explicit public interfaces for your React modules.

Organizing React projects into modules has been widely adopted by the React community. The core idea is that instead of organizing your projects files by type (“function first, feature second”):

src/
    components/
        app/
        todos/
        users/
            user-details.js
            user-details.css
            users.js
            users.css
            user-list.js
            user-list.css
    actions/
        app-actions.js
        todo-actions.js
        user-actions.js
    reducers/
        app-reducer.js
        todo-reducer.js
        user-reducer.js
    constants/
    utils/

You flip that around and organize by modules (“feature first, function second”):

src/
    base/
    modules/
        app/
        todos/
        users/
            __tests__/
            components/
                UserDetails/
                Users/
                    __tests__/
                    index.js
                    styles.css
                UsersList/
                index.js
            actions.js
            actionTypes.js
            constants.js
            index.js
            reducer.js
            selectors.js
    shared/
    utils/
    index.css
    index.js

This method of organizing has a number of benefits:

1. It decreases coupling and increases cohesion between the different sections of your apps, effectively reducing cognitive load while developing.
2. Since related files are co-located, there is less jumping around while developing (i.e., when adding a feature that requires changing actions, reducers, and components, they are all right there together).
3. You can use index.js to create a public interface for your different modules.

This last point is, in my opinion, one of the most subtle but useful benefits of this organizational structure. In ES6, having an index.js file in a folder lets you perform an import from the folder implicitly without specifying the index.js in the import statement – just like how web servers will serve up the index.html in a folder without you needing to explicitly put the index.html in the URL.

This gives you some semblance of control over what you export from the module and therefore what you can import and use from another section of your app. In other words, this allows you to create a public interface to expose certain files while keeping others “private”.

export { default as App } from "./App";
export { default as Home } from "./Home";
export { default as Login } from "./Login";
export { default as Navigation } from "./Navigation";
export { default as NotFound } from "./NotFound";
export { default as Signup } from "./Signup";

In this example, since we are talking about src/modules/app/index.js, it is describing which files are publicly exported from the app module.

1. It gives a clear picture of which components are used throughout the rest of the application.
2. It communicates that the rest of the files inside the app folder are only ever used inside the app module.

When you want to import something from a module (e.g., for a <Route />), you can do so quite cleanly in a single import statement:

import { Home, Login, NotFound, Signup } from "../modules/app";
import { Todos } from "../modules/todos";
import { Users } from "../modules/users";

At the end of the day, this is all just syntactic sugar. It is still possible to disregard the guidelines and create files anywhere or import files by deep linking into the folder structure. However, by organizing your application into modules, and then using index.js to re-export files as a public interface, you can attempt to communicate about intended usage to both other developers and future-you.

For more information about this topic, I highly recommend reading Three Rules For Structuring (Redux) Applications by Jack Hsu as well as How to better Organize Your React Applications by Alexis Mangin.