Modern JavaScript Module Boundaries That Scale

Two summers ago I spent a weekend teasing apart an analytics bundle because a helper imported the entire dashboard layer. That refactor reminded me that JavaScript modules are only useful when their boundaries make sense to the humans on call.

These days I sketch module boundaries on paper before touching the keyboard. I list the user journeys, mark the data they need, and decide which functions actually deserve to live together.

When a teammate asks for guidance I give them a simple questionnaire: what does this module produce, what does it depend on, and how do we swap it out. If we cannot answer within a minute, the boundary is muddy.

• Prefer named exports for stable APIs and default exports for leaf utilities.

• Keep cross-domain imports behind index files so refactors are scoped to one folder.

1import { fetchReport } from "./analytics";
2
3export const buildSummary = (clock, store) => {
4  const data = fetchReport(clock());
5  return store.persist(data);
6};
Copy

By threading dependencies through function arguments instead of hidden imports I can test features with stubbed clocks and stores.

Our build step runs a lightweight dependency graph check with madge; if a new import crosses a domain boundary the script fails before review.

Before shipping I skim the bundle analyzer to confirm lazy chunks stay slim and jot down the boundary decisions in the pull request so future me remembers why.