Static Imports Are Undermining JavaScript’s Isomorphism

--- title: Static Imports Are Undermining JavaScript’s Isomorphism published: true description: Early binding reduces runtime universality. Dependency Injection restores control at the composition root. tags: #javascript #webdev #architecture #designpatterns # cover_image: https://direct_url_to_image.jpg # Use a ratio of 100:42 for best results. # published_at: 2026-02-24 14:51 +0000 --- ## TL;DR - Static imports bind dependencies at module-load time. - Early binding encodes platform assumptions. - Declared dependencies move those decisions to the composition root. - This is not a new module system. It is standard Dependency Injection applied at the module level. --- JavaScript runs natively in both the browser and on the server. That makes true isomorphism possible. And yet modern JavaScript architecture quietly works against it. Consider: ```js import fs from "node:fs"; ``` This line embeds a Node-only capability directly into the module. A browser cannot satisfy `"node:fs"` by default. The module is no longer isomorphic. The issue is not `fs`. The issue is _early binding_. Static imports resolve dependencies during module evaluation. The host fixes the graph before your code runs. If a dependency is platform-specific, the module becomes platform-specific. --- ## Making dependencies explicit Instead of binding immediately, a module can declare what it needs. ```js // user-service.mjs export const __deps__ = { fs: "node:fs", logger: "./logger.mjs", }; export default function makeUserService({ fs, logger }) { return { readUserJson(path) { const raw = fs.readFileSync(path, "utf8"); logger.log(`Read ${raw.length} bytes`); return JSON.parse(raw); }, }; } ``` The module imports nothing directly. It declares a dependency contract and receives concrete implementations from the outside. This is Dependency Injection applied at the module level. The composition root decides what gets passed in. --- ## Manual composition root ### Node ```js // node-entry.mjs import fs from "node:fs"; import logger from "./logger.mjs"; import makeUserService from "./user-service.mjs"; const service = makeUserService({ fs, logger }); ``` ### Browser ```js // browser-entry.mjs import fsAdapter from "./browser-fs-adapter.mjs"; import logger from "./logger.mjs"; import makeUserService from "./user-service.mjs"; const service = makeUserService({ fs: fsAdapter, logger, }); ``` The module did not change. Only the composition root changed. Platform decisions stay at the edge of the system — and because dependencies are injected explicitly, tests can pass fakes directly instead of mocking module imports. --- ## Automating composition Because the contract is exposed via `__deps__`, the composition root can be made data-driven: ```js // link.mjs export async function link(entrySpecifier, overrides = {}) { const mod = await import(entrySpecifier); const depsSpec = mod.__deps__ ?? {}; const deps = {}; for (const [name, specifier] of Object.entries(depsSpec)) { const finalSpecifier = overrides[specifier] ?? specifier; const imported = await import(finalSpecifier); deps[name] = imported.default ?? imported; } return mod.default(deps); } ``` ### Node ```js const service = await link("./user-service.mjs"); ``` ### Browser ```js const service = await link("./user-service.mjs", { "node:fs": "./browser-fs-adapter.mjs", }); ``` Binding becomes explicit program logic, not loader side effects. --- ## How this differs from import maps and `exports` - **Import maps** control specifier resolution at load time (host-level). - **`package.json` exports** select entry points per environment (package-level). - **Bundlers** optimize graphs at build time. - **Composition root + DI** decides which concrete capabilities a module receives at runtime (application-level). Import maps answer: _Where is this module?_ Composition root answers: _Which capability does this module receive?_ Different layers, different concerns. --- ## Trade-offs This approach is not free: - You lose some static analyzability and tree-shaking precision. - TypeScript integration becomes more manual. - It’s unnecessary for small or purely single-runtime apps. - It introduces architectural discipline (composition root). This is a tool, not a default. --- ## When to use it Use it when: - You want true cross-runtime modules (Node + browser + edge). - You want environment decisions centralized. - You care about testability without heavy mocking. - You want explicit capability boundaries. Do not use it when: - Your app is single-runtime. - Build-time optimization and tree-shaking are primary concerns. - Simplicity outweighs architectural flexibility. --- Static imports are not wrong. They are efficient and idiomatic. But they bind early. And early binding encodes platform assumptions. If we care about preserving JavaScript’s isomorphism, we should be deliberate about where binding happens. Because once a module binds to a platform capability during evaluation, it has already chosen its platform.