Extend a theme from a base theme

This article describes how to extend a theme from a base theme for a Microsoft Dynamics 365 Commerce e-commerce site.

By using the Dynamics 365 Commerce online store extensibility software development kit (SDK), you can create either standalone themes or themes that extend a base theme. For example, you can have a base theme that defines Cascading Style Sheets (CSS) styles for modules, module view extensions, and module definition extensions. You can then have a different theme, or even a set of themes, that adds changes on top of the base theme. This capability is helpful when a single Dynamics 365 environment has multiple online sites that use different theme branding.

Specify a base theme

To specify the base theme for a theme, edit the theme definition file, and add a $ref section that points to the base theme.

In the following example, the $ref section references the fabrikam sample theme included as part of the module library.

{
    "$ref": "@msdyn365-commerce-modules/fabrikam-design-kit/dist/lib/modules/fabrikam/fabrikam.definition.json",
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "adventureworks",
    "name": "adventureworks"
}

Examples

In the following example, use the add-theme command-line interface (CLI) command to create a base theme.

yarn msdyn365 add-theme base

Here's the definition file for the base theme that you create.

basetheme.definition.json

{
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "base",
    "name": "base"
}

Next, use the CLI command to create a theme named extended.

yarn msdyn365 add-theme extended

The definition file for the extended theme can now reference the base theme by using a relative path, as shown here.

extended.definition.json

{
    "$ref": "../base/base.definition.json",
    "$type": "themeModule",
    "description": "This is SDK template theme module",
    "friendlyName": "extended",
    "name": "extended"
}

Include base theme styles

By default, the extended theme doesn't include base theme styles. To include the base theme styles, add a reference in the extended.theme.scss file, as shown here. This example also shows how to add other styles.

extended.theme.scss

@import "../../base/styles/base.theme.scss";

body {
    background-color: red;
}

The following example resembles the previous example. It shows that you can also add a reference to the base theme in the extended.definition.scss.json file, if you want.

extended.definition.scss.json

{
    "$ref": "../../base/styles/base.definition.scss.json",
    "name": "extended"
}

Additional resources

Theming overview

Create a theme

Configure theme settings

Configure theme style presets

Extend a theme to add module extensions

Override a module library component in a theme

Add custom resources to your customization code