stnd.build

Cross-Module Import Violation

Error: [ERR_CROSS_MODULE_IMPORT] Illegal cross-module import from sibling feature module. Law #4: Vertical-slice modules must never import from sibling feature modules directly.


The Problem

A file inside a feature module (modules/A/...) attempts to import code directly from a sibling feature module (modules/B/...) instead of communicating via the foundation core spine (@modules/core) or framework packages (@stnd/*).

// Inside modules/writer/toolbar.ts (Illegal sibling import)
import { openModal } from "@modules/launcher/modal.js";
import { formatTag } from "../tags/formatter.js";

The Why

Standard architecture is founded on Vertical-Slice Isolation (Law #4):

  1. Modules must remain independently mountable, testable, and removable: If modules/writer directly imports modules/launcher, removing or disabling launcher will break writer at build time.
  2. Coupling creates spaghetti architecture: Direct sibling-to-sibling imports turn a clean modular codebase into an tangled web of implicit cross-dependencies.
  3. One-Way Dependency Flow: Dependencies in Standard only flow in one direction:
    $$\text{Feature Module} \longrightarrow \text{Foundation Core (@modules/core)} \longrightarrow \text{Framework Packages (@stnd/*)}$$

The Solution

Choose one of three approved architectural patterns:

1. Route through the Foundation Core (@modules/core)

If the functionality is a domain model, shared state store, or essential primitive needed across features, move it into modules/core/:

// Compliant
import { openModal } from "@modules/core/modal.js";

2. Extract into a framework package (@stnd/*)

If the utility is generic and reusable across multiple applications, extract it into a package in packages/*:

// Compliant
import { formatTag } from "@stnd/utils";

3. Use the Unified Hooks System

If the two feature modules need to interact, go through a hook instead of an import. Two kinds, depending on what crosses the boundary:

---
// UI: the host opens a zone, the other module fills it from its manifest
import Hook from "@stnd/core/Hook";
---

<Hook zone="writer:toolbar" props={{ note }} />
// modules/launcher/index.module.js
hooks: { "writer:toolbar": ["./components/OpenLauncherButton.astro"] }
// Logic: fan a call out to whoever listens
import { runHook } from "virtual:stnd/hooks";
await runHook("launcher:open", { view: "modal" });

See Hooks & Extension Points. The mirror case — the core importing a feature — has its own page: Foundation Imports a Feature Module.