How to Choose the Right Refactor Mode

Refactor mode selection is about the change boundary, not only the target name. Choose the mode that matches whether you are changing block instances, shared-entity references, or the shared entity definition itself.

Start with the change boundary #

A Refactor mode should be selected only after you can describe the desired change boundary in plain language.

• Change this exact block variant where it appears.
• Stop these matching sources from referencing this shared entity.
• Update the shared entity definition that every reference should inherit.

Mode comparison #

• block_instance: best when one block variant inside indexed content should be replaced without changing a shared definition everywhere.
• entity_reference: best when matching sources should stop pointing at a shared pattern, template part, or navigation, while the shared definition remains intact.
• entity_definition: best when the shared pattern, template part, or navigation itself should be updated at the source of truth.

Common mode-selection mistakes #

• Using entity_definition when only a subset of references should change can widen the impact too much.
• Using entity_reference when the real goal is to edit the shared entity definition can create repeated follow-up work.
• Using block_instance for a shared-definition problem can miss the cleaner source-of-truth change.

Decision checks before preview #

Before you preview the batch, run through a short decision check that ties the selected mode to the intended outcome.

• Ask whether the shared definition itself should change everywhere or only selected sources should stop using it.
• Confirm whether the thing you are replacing is a block instance in content or a shared entity relationship.
• Review source evidence first so the target and scope are grounded in a fresh baseline.

Where to go next #