Upgrade Customized Components

When you customize built-in React components in your storefront and Salesforce later releases updates to those components, you need a strategy to adopt the improvements while preserving your customizations. Either merge updates without conflict, or maintain separate copies and use Vite build-time aliasing. Select the approach that best fits your team’s workflow and the extent of your customizations.

If you’ve modified a component’s source code and want to adopt Salesforce updates to that component, merge the changes. For straightforward cases with minimal code conflicts, a supervised Git merge can be sufficient. Carefully review all changes during the merge process to ensure your customizations are preserved while incorporating Salesforce improvements.

  • Your customizations are minimal.
  • Code conflicts are straightforward to resolve.
  • You want to maintain a single version of each component.
  • You’re comfortable with Git merge workflows.

Advantages:

  • Automatically receive Salesforce improvements and bug fixes.
  • Maintain a single version of each component (no code duplication).
  • Stay in sync with upstream changes.
  • Simpler project structure with fewer files to manage.

Disadvantages:

  • Potential merge conflicts when Salesforce releases updates.
  • Requires immediate conflict resolution to adopt updates.
  • May require rework of customizations if Salesforce makes significant structural changes.
  • Less predictable upgrade process.

To reduce merge complexity, maintain customized copies of components in a separate directory and use Vite’s build-time aliasing to override the built-in implementations. This approach prevents Git conflicts and simplifies adoption of upstream template updates.

  • You have extensive customizations.
  • Merge conflicts are complex or frequent.
  • You prefer explicit control over when to adopt Salesforce updates.
  • You want to minimize disruption during Storefront Next releases.
  1. Create a separate directory for your customized components (for example, /customizations).
  2. Copy the component you want to customize to this directory.
  3. Modify your copy as needed.
  4. Configure Vite to use your custom component instead of the original.

Use Vite’s resolve.alias configuration to replace the original component with your customized version.

For more information about Vite’s aliasing capabilities, see the Vite resolve.alias documentation.

Advantages:

  • Eliminates Git merge conflicts when Salesforce updates components.
  • Original components remain untouched.
  • Clear separation between out-of-the-box and customized code.

Disadvantages:

  • You don’t automatically receive Salesforce improvements.
  • You must manually merge Salesforce updates into your customized copies.
  • Requires maintaining awareness of upstream changes.

The Storefront Next extension mechanism and UI target functionality are designed for independent software vendors (ISVs) and partners building reusable solutions. These features are not intended for customizing individual templates in your storefront. Use the methods described in this guide for component customization instead.