Static Imports Are Undermining JavaScript’s Isomorphism

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:

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.

// 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

// 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

// 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:

// 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

const service = await link("./user-service.mjs");

Browser

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.

Comments

[Péter “Poetro” Galiba]

Browser can import any package, if you have defined where to import the package from defined by the developer.mozilla.org/en-US/docs/W...
Obviously it should match the expected API, so the code won't break.

[Alex Gusev]

You’re absolutely right that the browser can import any package via import maps. Static import is early binding - the dependency is resolved at module load time. What I’m exploring is late binding - dependencies are declared but resolved at runtime. It’s not about capability, it’s a different architectural choice.