Organizing Large TypeScript Projects

Large projects become easier to maintain when source code is grouped by feature and responsibility. Keep public module interfaces small; do not expose database implementation details to UI code. A feature folder can contain its types, domain operations, tests, and adapter while the application entry point wires dependencies together.

The Account type and activeIds function can form one feature's public interface. Other modules depend on this contract rather than reaching into private arrays, storage, or internal files.

A massive index.ts barrel exporting every internal symbol makes dependencies harder to see and can introduce circular imports.

This source was compiled using TypeScript 5.8.3 with strict checking, then executed with Node.js 22.16.0. Its stdout below is the actual captured output. The core logic is runnable without a framework or a remote API; integration-specific examples appear in a separate lab when needed.

TypeScript source

type Account = { id: string; active: boolean };
function activeIds(accounts: readonly Account[]): string[] {
  return accounts.filter(a => a.active).map(a => a.id);
}
const accounts: Account[] = [{ id: "A1", active: true }, { id: "A2", active: false }];
console.log(activeIds(accounts).join(", "));

Verified output

A1

Compile: npx tsc --strict --target es2022 --module commonjs organizing-large-projects.ts; run: node organizing-large-projects.js. For examples importing node: modules, install @types/node as a development dependency; for browser or React projects use the separate lab setup.

The Account type and activeIds function can form one feature's public interface. Other modules depend on this contract rather than reaching into private arrays, storage, or internal files.

Before editing the code, predict what the output will be for one changed input. Run it and compare your prediction with the actual result.

A massive index.ts barrel exporting every internal symbol makes dependencies harder to see and can introduce circular imports.

Determine whether the issue belongs to the type system, a trust boundary, or actual runtime behavior before choosing a correction.

Sketch a src/features/accounts layout with account.ts, service.ts, storage.ts, and account.test.ts. Decide which exports other features actually require.

Record expected success and failure outcomes, run the code, and compare the observed behavior. Keep the exercise compatible with strict type checking.

The Account type and activeIds function can form one feature's public interface. Other modules depend on this contract rather than reaching into private arrays, storage, or internal files.

Apply the same reasoning to the practice task, then integrate it into a real app only when the runtime and dependency setup are ready.