Shadow a component or module

Shadow a component or module#

Component or module shadowing allows you to override a component from an existing package in a clean and structured way, without directly modifying third-party code. This technique is particularly useful for customizing the behavior or appearance of specific components in Volto or any add-ons.

This mechanism is powered by Webpack's resolve.alias, which maps a module path to an alternative file or folder. Webpack resolves the override at build time, replacing the original module with your custom implementation.

To shadow a component, perform the following tasks.

  • Locate the component you want to override or shadow.

  • Replicate the component's original folder structure inside a src/customizations folder in your add-on.

Folders and files hierarchy structure pattern for shadowing#

To shadow components, you must follow a file structure pattern.

Customize Volto core components or modules#

Assume the component you want to shadow is located in Volto core at node_modules/@plone/volto/src/components/theme/Logo/Logo.svg.

To customize a Volto core component, the first folder must be volto. Replicate this structure under src/customizations as shown.

customizations/
└── volto/
    └── components/
        └── theme/
            └── Logo/
                └── Logo.svg

Note

Please note the absence of the src/ folder in the shadowed module paths. This is because the build ignores and removes the src/ prefix when resolving modules.

Tip

Use absolute imports in your shadowed modules to avoid resolution issues.

Customize add-ons components or modules#

Assume the component you want to shadow is located in an add-on at node_modules/@kitconcept/volto-light-theme/src/components/Header/Header.tsx.

To customize this add-on component, the first folder must be the full name of the add-on, @kitconcept/volto-light-theme. The full filepath must include the namespace, if any, separated in folders. You'll need to replicate this structure under src/customizations as shown.

customizations/
└── @kitconcept/
    └── volto-light-theme/
        └── components/
            └── Header/
                └── Header.tsx

Debug shadowing#

You can enable an environment variable to help debug shadowing issues. Set the DEBUG environment variable to shadowing:* to see detailed logs about the module resolution process.

DEBUG=volto:shadowing pnpm start

Identify components to shadow#

To determine what and where to shadow:

  • Use the React Developer Tools add-on for either Firefox or Chrome to inspect the live DOM tree and identify component names.

  • Search those component names in the corresponding source package inside node_modules/.

  • Follow import paths and folder structures to map to the original file.

Caution when upgrading#

Warning

If you update a dependency or add-on that contains shadowed components, always verify whether the shadowed component's structure, API, or dependencies have changed.

Failure to adapt your shadowed code to the new version may break your application silently or cause unexpected behavior.

Clarification: only registered add-ons can be shadowed#

Shadowing only works with registered add-ons (see Install an add-on in Volto) that are explicitly declared as such in registry.config.ts. If you attempt to shadow a module from a package that is not registered as an add-on, the override will not be resolved, and your changes will be silently ignored. Always ensure the package you want to shadow is installed and registered in your application configuration.

Summary#

  • Component shadowing is safe and modular when done properly.

  • The key is to mirror the original file path in the src/customizations folder.

  • Only registered add-ons can be shadowed.

  • Keep your shadowed components up to date with upstream changes.

Contents