File shadowing

Build projects on top of projects

Mosaic introduces the concept of shadowing (overriding) files. Shadowing is a feature of themes.

The shadowing mechanism will only function for files in the src and public directories your theme, parent theme or extensions.

Shadow a parent theme

Instruction

1. Create a child theme, set the mosaic.parentTheme value of its package.json to the proper parent theme. This parent theme should be installed into your child theme.

2. Determine the file of the parent theme you are willing to shadow.

3. Create a file on the same path of the child theme.

4. Implement functions/classes/variables which are going to be provided to the application instead of the initial ones. You may or may not use the original functionality within these values.

5. Ensure that all of the exports of the parent theme are also exported from this file.

Example

1. Have a child theme created, @example/parent-theme is installed into it and set as mosaic.parentTheme field in the package.json

2. Select file @example/parent-theme/src/AddToCart.component.js

3. Create file src/AddToCart.component.js in the child theme

4. Override its functionality

5. Ensure re-exports from the child theme's file

In case the package.jsonfieldmosaic.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.

Shadow an extension

Instruction

1. Work with a theme, in which some extension is installed

2. Determine the file of the extension you are willing to shadow.

3. Create a file on the path of the child theme that is build as follows: src/<module name>/<relative path> where <relative path> is relative to the extension's src directory

4. Implement functions/classes/variables which are going to be provided to the application instead of the initial ones. You may or may not use the original functionality within these values.

5. Ensure that all of the exports of the parent theme are also exported from this file.

Example

1. Have a theme my-theme and an extension @example/extension-1 installed into it

2. Select a file to override: @example/extension-1/src/DataProvid

3. Create a file on the following path: my-theme/src/@example/extension-1/DataProvider.js

4. Override its functionality

5. Ensure re-exports from the child theme's file

Caveat

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.

Sequence of preference

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

1. Your theme's files

2. Parent theme's files

3. Extensions files

An extension cannot override another extension's file