Well-designed TypeScript module boundaries make dependencies visible, APIs intentional, and refactoring safer. This guide gives you a practical checklist for choosing between direct exports, barrel files, package entry points, and subpath exports—while reducing circular dependencies and accidental public APIs.
Overview
A module boundary is the point where one part of an application exposes functionality to another. In a small project, that boundary may be a single exported function. In a larger application or package, it can include folders, index.ts files, package entry points, and the exports field in package.json.
The goal is not to minimize the number of files or imports. The goal is to make ownership and supported usage clear. A good boundary answers three questions:
- Which modules are allowed to depend on this code?
- Which names are part of the supported API?
- Can the dependency direction remain one-way as the project grows?
TypeScript checks types, but it does not automatically design your architecture. An export can be type-safe and still create a cycle, expose an implementation detail, or make a package difficult to change. Treat exports as an architectural decision, not merely an import convenience.
Compare the main export patterns
| Pattern | Best fit | Main advantage | Risk to watch |
|---|---|---|---|
| Direct exports | Application modules and small features | Dependencies remain explicit | Import paths may become longer |
| Local index file | A cohesive feature folder | Provides a convenient local boundary | Can hide dependency direction |
| Package entry point | A library or separately consumed package | Defines a deliberate public API | Internal files may be exposed accidentally |
| Subpath exports | Packages with multiple supported entry points | Separates public areas explicitly | Requires matching build and type declarations |
Checklist by scenario
When organizing an application feature
- Start with direct imports. Import from the file that owns the symbol while the feature is taking shape. This makes the dependency graph easy to inspect.
- Separate public feature code from implementation details. For example, keep request handlers, domain logic, and database adapters in distinct areas rather than exporting everything from one folder.
- Define direction before adding convenience exports. A UI component may depend on a service, while the service should not import from the UI folder. If both need shared types, move those types to a lower-level module.
- Add a local barrel only for a stable group. A feature-level
index.tsis useful when several nearby consumers need the same small public surface. It is less useful when it re-exports every file in the directory.
// features/orders/index.ts
export { createOrder } from './createOrder';
export type { Order, OrderInput } from './model';
// A consumer imports the feature boundary, not its internals.
import { createOrder, type OrderInput } from './features/orders';
When building a reusable package
- Write down the public API. Decide which functions, classes, types, and constants consumers may rely on. Do not use the contents of a folder as the definition of your API.
- Create a deliberate package entry point. Re-export public symbols from a dedicated file such as
src/index.ts, then build that file as the package root. - Keep internal imports internal. Source files inside the package can use relative imports or approved internal aliases. Consumers should not need to import from
dist/internalor similarly unstable paths. - Use subpath exports when separate areas are genuinely supported. For example, a package might expose
your-packageandyour-package/testing. Each path should have a clear purpose and its own tests.
// package.json
{
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
},
"./testing": {
"types": "./dist/testing.d.ts",
"import": "./dist/testing.js"
}
}
}
The exact conditions and file layout must match the package's build output and the environments it supports. Check the behavior of your TypeScript configuration, bundler, test runner, and runtime together rather than assuming that one resolver's behavior represents all of them. The TypeScript tsconfig guide is useful when module and resolution settings need a broader review.
When investigating a circular dependency
- Find the shortest cycle. Trace imports until you return to the starting module. Ignore unrelated warnings at first.
- Look for a barrel in the middle. A file that re-exports many modules can turn an apparently one-way import into a cycle.
- Replace broad imports with direct imports. This often confirms whether the barrel is the source of the cycle.
- Move shared contracts downward. Interfaces, discriminated unions, and small value objects often belong in a dependency-light contracts module.
- Use type-only imports where appropriate.
import typecommunicates that a dependency is erased from runtime output. It does not fix every design problem, but it can prevent a type reference from becoming a runtime edge.
// Prefer this when only the type is needed.
import type { User } from '../users/model';
// Keep runtime imports separate and intentional.
import { formatUserName } from '../users/formatUserName';
What to double-check
- Runtime versus type dependencies: inspect whether an import is needed at runtime or only during type checking. Compiler settings such as
verbatimModuleSyntaxcan make import intent more explicit, but the surrounding toolchain must support the resulting syntax. - Module resolution consistency: verify that the TypeScript compiler, editor, test runner, bundler, and production runtime resolve the same paths. A project can type-check successfully while tests or production builds fail on an unsupported alias or export condition.
- Declaration output: for libraries, confirm that generated
.d.tsfiles do not reference private paths that consumers cannot resolve. - Package entry points: test the package as an installed consumer would. A passing source-level test does not prove that the published package exposes the intended files.
- Import direction: establish a simple layering rule, such as presentation → application → domain → infrastructure. Shared code should sit below the layers that consume it, not in a catch-all folder imported by everything.
- Tree-shaking and side effects: a broad barrel can make side-effectful modules easier to load unintentionally. Keep initialization code out of general-purpose export files where possible.
For a project-wide investigation, record each module's allowed consumers and public exports before changing paths. This turns a confusing import cleanup into a bounded architecture task. If the changes produce unrelated compiler messages, use a structured debugging process such as the one in Fixing Common TypeScript Errors.
Common mistakes
Creating a barrel for every folder
An index.ts file is not automatically a boundary. If it exports every implementation file, it becomes a second directory listing with hidden dependency behavior. Prefer a small, curated list of stable exports.
Importing through a higher-level barrel internally
Application code often imports from a root barrel because the path is short. That convenience can cause a low-level module to load higher-level code or re-enter its own export graph. Within a package, use lower-level direct imports when they make dependency direction clearer.
Confusing exported types with a stable API
Exporting a type does not mean its shape can never change, but consumers may still depend on it. Mark internal types as internal by keeping them unexported, and expose purpose-built input and output types instead of database records or framework-specific objects.
Assuming aliases solve architecture
A path alias improves readability; it does not create a dependency boundary. If an alias points to an unrestricted source tree, it may make unsafe imports easier to write. Pair aliases with folder conventions, lint rules, package boundaries, or project references where the project needs enforcement. See the TypeScript project references guide for a related approach to separating larger codebases.
Fixing cycles by disabling checks
Suppressing a warning or changing module settings may hide a symptom without correcting initialization order or ownership. First identify whether the cycle is type-only, runtime, or both; then remove the unnecessary edge or extract a lower-level contract.
When to revisit
Review module boundaries before a major folder reorganization, package split, framework migration, or change to the build and test toolchain. Also revisit them when a new team repeatedly asks which import path is supported, when circular dependency warnings appear, or when consumers reach into undocumented internal files.
Use this short review workflow:
- List every public package entry point and feature-level barrel.
- Compare those exports with the imports used in documentation and tests.
- Search for deep imports into build output or private folders.
- Generate or inspect the dependency graph and investigate cycles.
- Build declarations and test the package from a clean consumer project.
- Remove exports that are not supported, or document the ones that are.
Tooling changes can affect module resolution, export conditions, declaration generation, and bundling. Re-run this checklist when those inputs change, not only when the application fails. A small, explicit public API and a one-way dependency graph will usually make the next refactor easier than another layer of export convenience.