File overrides

ScandiPWA introduces the concept of "overriding" files. Overrides are a feature of ScandiPWA themes.

To override a file - means to create a file which will be used instead of some other file. You can override files of any extension or parent theme.

To override a file of a parent theme

Instruction

1. Determine your parent theme location:

   1. Locate package.json in your theme and pay attention to field scandipwa.parentTheme

   2. Navigate to node_modules/<PARENT THEME NAME>

2. Locate the file you intend to override in a parent theme folder

3. Create a new file in your theme, which:

   1. Has the same name as the original file

   2. Is located in the same folder (relative to src) as the original file

In case the package.jsonfieldscandipwa.parentThemeis empty, your theme is considered to be a root theme. In this case, parent theme overrides will not function, as there is simply no parent theme.

Example

To override a file AddToCart.component.js:

1. Check our theme's package.json file:

   1. The value of scandipwa.parentTheme is @scandipwa/scandipwa

   2. The location of a parent theme therefore is node_module/@scandipwa/scandipwa

2. Search for AddToCart.component.js in a parent theme files:

   1. The file was found in src/component/AddToCart/AddToCart.component.js

3. Create a new file in our theme:

   1. Filename is AddToCart.component.js

   2. Folder it should be located in is src/component/AddToCart

To override an extension file

Instruction

1. Determine an extension the file you intend to override belongs to

   1. Run a theme using the start script

   2. Use the browser's developer console to search for a filename

2. Locate the file you intend to override in the extension

3. Create a new folder in your theme's src folder, which matches the extension name

   1. You can find the extension name in the name field of the extension's package.json

4. Create a new file in your theme, which:

   1. Has the same name as the original file

   2. Is located in the same folder (relative to src) as the original file, but under the newly created extension specific folder. The pattern for the folder to create extension in is src/<EXTENSION NAME>/<PATH AS IS EXTENSION>.

Extension might also provision a path. In example, the @scandipwa/m2-theme provision the public/index.php file. To override this file, you need to create the exact path in your application theme, without creating the folder matching extension name.

Example

To override a file PayPal.component.js:

1. Using the Google Chrome, search for the PayPal.component.js

   1. The search results point us to node_modules/@scandipwa/pay-pal/src/component/PayPal/PayPal.component.js

   2. The extension, therefore is @scandipwa/pay-pal

   3. And the file is located in src/component/PayPal/PayPal.component.js

2. Create a new folder matching the extension name: src/@scandipwa/pay-pal

3. Create a new file in our theme:

   1. Filename is PayPal.component.js

   2. Folder it should be located in is src/@scandipwa/pay-pal/component/PayPal

The "overrides", however, are optional. You can freely create folders and files in ScandiPWA folder. The override-mechanism will only function for files in the src and public folders your theme, parent theme or extensions.

Watch-out!

If the file you created will unintentionally match extension's or parent theme's path, it will override it. Be careful not to break the functionality, while creating new files and folders.

The sequence of preference

ScandiPWA implements following sequence of override preference (from highest priority to lowest):

1. Your theme files

2. Your theme's parent themes files

3. Extensions files

An extension can not override another extension's file. This feature is only available for themes.