ScandiPWA is installed as an NPM module in the node_modules directory. This means we can not modify its source directly. We still have to, in order to change the application's appearance or extend its functionality. In order to do it, 2 options exist:

• Create an override - create a new file under the same location as in the original theme. Works only for themes. Works well for UI extension that is not planned to be reused on other projects.
• Create a plugin - create a new plugin file and plugin to some namespace. Works for both themes and extensions. Works well for the extension of the application logic. Can be easily packed and reused on another project if needed.

<aside> ➡️ This guide will focus on overriding files. To extend the logic of the app, please use the plugins. How to create a plugin?

</aside>

What is a file override?

Overriding a file - means creating a file that will be used instead of some other file. ScandiPWA introduces the concept of the "override mechanism", which is used for "overriding" files as a convenient customization feature.

Using the override mechanism, you are able to change any part of a ScandiPWA application, including styling, user interaction, page structure, or custom functionality. Any part of the theme that you don't override will fall back to the default implementation.

Video: Overriding a file

How does the override mechanism work?

Think about it as a stack, and each theme is a layer of the stack. ScandiPWA's parent theme is at the bottom layer of the stack and we build the stack from bottom to top, you can have an unlimited stack of themes overriding parts of/adding new functionalities to the previous theme on the stack. Take a look at the diagram here:

In this diagram, we have 2 entities:

• The parent theme of My Project is ScandiPWA
• The My Project is a child theme of ScandiPWA

What's a parent theme?

Theme - is a collection of components, which implements a presentation layer that is unique to your application. Themes can stack on top of each other. A theme that another theme is based on is called a parent theme. ScandiPWA's parent theme is the default front-end template that you see when you first run ScandiPWA.

The Override Mechanism is about taking a base parent theme and overriding parts of it to create a new, customized theme. By default, that parent theme is @scandipwa/scandipwa, the standard ScandiPWA theme – but it doesn't have to be!

Any theme created using create-scandipwa-app can be extended. Read the CSA documentation to learn more.

Why should I override a parent theme?

Parent theme comes with a lot itself. However, you may want to modify some of what it offers for the project's needs, particularly you can:

• Change the layout or styling of any component or page
• Modify any component's behavior
• Add new components with custom functionality
• Add new pages to your application
• Remove any unwanted functionality

What's an extension?

Extension - is a reusable, isolated part of your application. It can contain a presentation layer, business logic, or even build configuration. How to create an extension?

Why should I override an extension?

If you want to add the functionality of an extension but also want to match its style to your website, you can install the extension and override its styles.

<aside> ➡️ The Override Mechanism is designed to be used for developing one specific theme. If you want to develop an extension that can be installed on multiple themes, take a look at How to create an extension?

</aside>

What can be overridden?

You can modify files of any extension or parent theme. You'll mostly need to modify 2 types of files:

• JavaScript files, if you wish to modify components, routes, query files, or functionality.
• Style files, if you want to modify the style of an element.

And most of the time the changes will affect either an extension or the parent theme, changing the looks or the functionality of a component there. What's a component?

How to override files?

1. Find the location of the code you'll override

First, you need to know which component or element you're targeting for changing its style or implementation in order to look for its source files to override. You can do that by following the toggle below:

• Where can you find the component source files?

However, you may not be targeting any particular component, but want to change routes of the website, change the Redux store behaviour, override query functions, import additional assets in your project's index HTML code, or change the styles of an extension:

Where can you find specific types of files?

Where can you find extension source files?

Installed extensions' source files can be found in node_modules/<EXTENSION_PACKAGE_NAME> directory. An example can be node_modules/scandi-dark-theme or node_modules/@scandipwa/pay-pal.

2. Choose the specific files you'll override

The main rule for overriding ScandiPWA theme files is to have the "Overrider" file on a similar path to the core file you'll be overriding. Afterward, everything you define in the "Overrider" file will be used instead.

<aside> ➡️ You should also have everything you override exported just like in the original file.

</aside>

Depending on what you override, whether the component itself, its styles, or something else, you should have one of the following questions:

How to override JavaScript classes?

How to override non-classes?

How to override extension files?

How to override styles?

Overriding index.html and index.php

<aside> ⚠️ If the file you created will unintentionally matches the extension's or parent theme's path name, it will override it. Be careful not to break the functionality of other files, while creating new files and folders.

</aside>