Skip to main content

Extracting a new module

This guide explains when and how to extract a new module from an existing project or module.

Why extract a module?​

  • Reuse: The feature is applicable beyond a single customer project or the feature is used in multiple modules. Extracting it reduces duplication and maintenance overhead.
  • Clear ownership: The functionality is self-contained and can evolve independently.
  • Upstream fit: If the change is a general improvement to a core module and is always required, talk to the original module owner to integrate it upstream instead of creating a separate module.

Potential drawbacks​

  • Operational overhead: Versioning, publishing, and changelog management add process complexity.
  • Coordination cost: Changes may require synchronized updates across multiple projects.
  • Fragmentation: Too many fine-grained modules can make discovery and dependency graphs harder to manage.
  • API rigidity: Stable public APIs slow down internal refactors and experimentation.
  • Dependency risk: More transitive dependencies increase the chance of conflicts and security updates.
  • Build times: Additional packages can lengthen CI and local install/transpile steps.

When to decide​

  • During feature development, you can work directly on your current project/module.
  • Once it becomes clear the functionality is reusable or self-contained, extract it into a dedicated module.
  • Experienced developers might identify the need for a separate module even before implementation starts.

Preparation​

  • Close the Designer to avoid unintended behaviors regarding the file movement/deletions while refactoring.
  • Identify all files that constitute the new module's scope:
    • If some changes are local and uncommitted, use git status or git diff to list them.
    • If some changes are already committed, determine the exact set of files (including modifications) that belong to the new module's functionality.
  • Create a new module following the guide.

Move code and define dependencies​

  • Move all relevant files into the new module, including:
    • normal data models (e.g., entities, contexts)
    • the linked files (e.g., processes or documentation) that are needed for the normal data models
    • Modifications that the new module builds upon
  • Declare only the required peerDependencies and dependencies for the new module.

Project cleanup​

  • Ensure the original project or module no longer contains files that now belong to the new module.
  • Make sure that there are no dangling process files in any subfolders of your original project or module.

Verification​

  • Start the Designer again and open both the new module and the existing project or module.
  • In the new module, run:
  • Check if all necessary data models are visible in the Designer.
  • If everything passes, publish the new module.

Integration​

  • Add the new module as a dependency to the existing project or module.