Auto-import ignores barrel (index.ts) when the imported folder name is a prefix of the importing file name

[alexicum]

🔎 Search Terms

auto-import index label:"Domain: LS: Auto-import"

🕗 Version & Regression Information

• This changed between versions 6.0.3 and 7.0.2

VSCode version: 1.134.0
Windows 11

⏯ Playground Link

Example

💻 Code

Project structure example:

utils/
  sum/
    index.ts    // re‑exports sum from sum.ts
    sum.ts
  sumA/
    index.ts    // re‑exports sumA from sumA.ts
    sumA.ts
  sumABNums/
    index.ts    // re‑exports sumABNums from sumABNums.ts
    sumABNums.ts
  sumAB.ts      // importing file (the issue occurs here)
  index.ts      // importing file (works correctly)

// src/utils/sumAB.ts
import { sum } from "./sum/sum.js";
import { sumA } from "./sumA/sumA.js";
import { sumABNums } from "./sumABNums/index.js";

console.log(sum, sumA, sumABNums)

// src/utils/index.ts
import { sum } from "./sum/index.js";
import { sumA } from "./sumA/index.js";
import { sumABNums } from "./sumABNums/index.js";

console.log(sum, sumA, sumABNums)

🙁 Actual behavior

In utils/sumAB.ts:
for modules sum and sumA (whose folder names are prefixes of the importing file name sumAB.ts), the suggestion points to the direct file: './sum/sum.js' and './sumA/sumA.js'.
The barrel path './sum/index.js' and './sumA/index.js' is not offered.

For sumABNums (folder name is longer than the importing file name, so it is not a prefix), the correct barrel path './sumABNums/index.js' is suggested.

In utils/index.ts (also at the same level), imports for all modules correctly resolve via their barrel files.

🙂 Expected behavior

The barrel path ('./sum/index.js', './sumA/index.js') should always be the preferred suggestion when it exists, regardless of how the folder name relates to the importing file name.

Additional information about the issue

The issue seems to occur specifically when the imported folder name is a prefix of the importing file name. If the names differ by at least one character in a way that breaks the prefix relationship (e.g., sum and sumB or sam), the barrel path is correctly suggested.

In 6.0.3 barrel files are always ignored (in both files: utils/sumAB.ts and utils/index.ts).

[andrewbranch]

What do you mean by “In 6.0.3 barrel files are always ignored (in both files: utils/sumAB.ts and utils/index.ts)”?

Can you explain why the barrel file should be prioritized over a direct path when the two paths are equal length? In CommonJS resolution where directory modules are supported, barrels win because the computed module specifier is shorter. In ESM resolution where you need a fully qualified relative file path, the barrel file and its sibling produce paths with an equal number of slashes. Importing from a barrel is widely regarded to be bad for tooling. Many people would request the exact opposite expected behavior. My view has generally been that we have a user preference for picking shorter paths so we should continue to respect that, but in ESM, the choice between a barrel import and a sibling direct import is completely arbitrary, and opinions will differ on what to choose. We may introduce a preference in the future, but I don't see a strong rationale for hard-coding a sort order until then.

[alexicum]

What do you mean by “In 6.0.3 barrel files are always ignored (in both files: utils/sumAB.ts and utils/index.ts)”?

TypeScript 6.0.3 with TSServer suggests same imports in both files utils/sumAB.ts and utils/index.ts:

import { sum } from "./sum/sum.js";
import { sumA } from "./sumA/sumA.js";
import { sumABNums } from "./sumABNums/sumABNums.js";

Tsgo suggests:

• utils/sumAB.ts:

// source file
import { sum } from "./sum/sum.js";
// source file
import { sumA } from "./sumA/sumA.js";
// index in both cases
import { sumABNums } from "./sumABNums/index.js";

• utils/index.ts

// index.js
import { sum } from "./sum/index.js";
// index.js
import { sumA } from "./sumA/index.js";
// index in both cases
import { sumABNums } from "./sumABNums/index.js";

The issue is not about whether barrels are good or bad. The issue is that the current algorithm yields different results depending on the:

• name of the importing file (prefix case).
• alphabetical order of files inside a folder #64034.

This makes auto‑import unpredictable and leads to inconsistent import styles within the same codebase.

..., but in ESM, the choice between a barrel import and a sibling direct import is completely arbitrary, and opinions will differ on what to choose.

Thank you for the thorough explanation. I understand your point about equal path lengths in ESM and the absence of a clear technical winner. That said, I acknowledge the practical concerns. Barrel files can negatively impact tool performance and tree-shaking ("sideEffects": false)

However, I’d like to offer a mental model that I believe is widely shared in the community:

• index.ts (or index.js) is the public interface of a module (directory). It abstracts internal implementation details.

When an index.ts exists, importing from it (or from the folder) signals that the consumer is using the public API of that module. Directly importing a sibling file (double.ts, product.tsx) bypasses that abstraction and exposes internal structure, making refactoring harder and reducing encapsulation.

Even when the path length is identical (in ESM), the semantic distinction remains:

• './utils/double/index.js' - "I’m using the public interface of the double module."
• './utils/double/double.js' - "I’m reaching into the internal files of the double module."

This is why I believe the barrel path should be preferred when it exists - not because it’s shorter, but because it respects the intended module boundary.

We may introduce a preference in the future, but I don't see a strong rationale for hard-coding a sort order until then

A future preference would be welcome, but until then, I would ask that the sorting logic at least be consistent — either always prefer index.ts when it exists, or never prefer it. The current mixed behavior is the problem.