27. Small Files and Barrels

27. Small Files and Barrels

Date: 2025-04-22

Status

Accepted

Context

In JavaScript/TypeScript projects, as the codebase grows, managing imports becomes increasingly complex. Two common patterns emerge to address this:

1. Small, focused files: Creating many small files, each with a single responsibility or component.
2. Barrel files: Using index files (often called “barrels”) to re-export multiple components from a single entry point.

A barrel file is an index.ts/js file that collects exports from multiple files and re-exports them. For example:

The bigger a file gets the harder it is to stay focused on what it is trying to accomplish. Also the bigger the files are harder for the AI to consume. Lots of small files are easier to find what you need and can make it easier to make sure that you have test coverage for everything.

Some teams like to have big files grouped by usage - for example a hooks.ts file that has all the hooks for a project. This gets overwhelming as the project grows. It also makes it harder to re use the code in other projects.

We have experimented with both (largely because the AI tends to make big messy files). We are goign to make it official

Decision

Where possible instead of having a big file with lots of different components,functions, or classes - it should become a directory with lots of files and an index.ts/js file to do the barrel import This makes it easy for end users to import the code and still allows developers to manage smaller files.

Consequences

What becomes easier or more difficult to do and any risks introduced by the change that will need to be mitigated.