Skip to main content

Modularization Pitfalls and Anti-Patterns

Modularization enables reuse, safer upgrades, and clear ownership when done correctly. However, recurring anti-patterns can erode these benefits and lead to brittle integrations, hidden coupling, and costly upgrades. This guide highlights common pitfalls and how to avoid them. Prefer explicit and stable extension mechanisms such as Extension Points and Services instead of ad hoc copies, overrides, or implicit dependencies, and treat build feedback as a first-class signal.

Copying Source Between Modules​

  • Problem: Copying files or models breaks modular boundaries and loses upstream improvements. This might happen if you copy a view to insert customer-specific elements.
  • Result: You miss updates from the original module, diverge over time, and increase maintenance.
  • Prefer: Delete unneeded elements in your module and extend via Extension Points. If you need to insert elements mid-structure (e.g., view templates), coordinate with the module author to add a suitable Extension Point.

Overriding Processes​

note

See Override Process for when to use overrides and associated risks.

  • Problem: You must maintain overridden JDito processes forever; upstream fixes won't flow in.
  • Result: Recurring effort and risk at every version upgrade.
  • Prefer: Services (global or entity) to hook logic; only override when necessary and document/track upstream changes.

Modifications of Existing Elements​

note

Do not confuse Extension Points and Services with Modifications. See Modification for pitfalls.

  • Problem: Modifications are not stable extension interfaces. Refactorings (renames/removals) in the source module can break them; value overrides may cause invalid states across versions.
  • Result: Fragile customizations and hidden runtime issues after updates.
  • Prefer: Use Extension Points or Services. After each dependency update, review all modifications and validate the transpiled result.

One‑Sided Extension Points​

note

See Extension Points for why “One‑Sided Extension Points” violate the mechanism.

  • Problem: Declaring an Extension Point and implementing it in the same module defeats their purpose and hurts traceability.
  • Result: Harder code reviews and unclear cross‑module contracts.
  • Prefer: Define Extension Points only in the owning module; implement them in dependent modules.

Excessive Dependencies​

note

See Dependency Types for the “Too Many Dependencies” anti-pattern.

  • Problem: Adding unneeded modules increases build time, security surface, and upgrade effort; it also risks hidden coupling.
  • Result: Harder upgrades and dependency conflicts.
  • Prefer: Keep dependency sets minimal and purposeful; routinely prune unused modules.

Transitive-Only Usage During Authoring​

note

See Transitive Dependencies for the general explanation.

  • Problem: Relying on transitive (undeclared) dependencies creates a hidden coupling that can break with resolution changes.
  • Result: Brittle authoring and unexpected failures.
  • Prefer: Declare all necessary modules directly (peerDependencies in modules; dependencies in projects) so they are visible and supported in the Designer.

Liquibase and Shared Tables​

note

See chapter Database Modularization for the general use case of database aliases.

  • Problem: Modifying shared/core tables from another module reduces upgrade safety.
  • Result: Cross-module coupling and migration risks.
  • Prefer: Create module-specific tables and aliases; only change shared tables when unavoidable, documenting rationale and impact.

Language Keys and Merging​

note

See chapter Internationalization for the general use case of language keys.

  • Problem: Editing foreign module language files directly or skipping partial transpile during analysis misses keys and overrides.
  • Result: Incomplete translations or lost overrides.
  • Prefer: Override keys in your package and run the partial transpile when analyzing keys to include modifications and extensions.

Ignoring Build and Transpile Logs​

  • Problem: Skipping log reviews, especially WARN and ERROR, hides real issues (conflicts, unresolved modifications, missing peerDependencies, failed injections at Extension Points/Services).
  • Impact: Broken or inconsistent dist output, silent runtime failures, upgrade regressions discovered late, and repeated CI failures.
  • Symptoms: "It works on my machine" inconsistencies, transient transpile errors, missing elements after deployment, or flaky behavior after upgrades.
  • Preferred Practice:
    • Treat WARN as actionable and ERROR as blocking. Do not proceed with deployment while they exist.
    • Always scan the "Output – Build" after transpile. Enable debug logs when needed.
    • Fix root causes promptly (e.g., resolve diamond conflicts, align dependencies, repair invalid modifications).
    • Make log checks part of code review and CI gates; fail pipelines on ERROR and critical WARN.
tip

See common log messages in the Transpile Logging section.