Add a New File to a Theme

When you customize a theme, you can also create new HTML, Sass, or asset files to meet your needs. The following procedure explains how to add a file to your theme and also includes steps for editing the theme’s manifest.json file. You need to edit the theme’s manifest to ensure the files that you add are compiled along with all other resources for the theme. For more information about the manifest file, see Edit the Theme Manifest.

Note:

To reference assets within your code, use the HTML and Sass helpers provided. See Managing Theme Assets for more information.

To create a new file for a theme:

Create your new HTML, Sass, or asset file in the correct location, as required.

File Type	Location Within Workspace/<THEME_DIRECTORY>/
HTML	Modules/<MODULE>/Templates
Sass	Modules/BaseSassStyles/Sass/reference-theme
Assets	assets

File Type

Location Within Workspace/<THEME_DIRECTORY>/

HTML

Modules/<MODULE>/Templates

Sass

Modules/BaseSassStyles/Sass/reference-theme

Assets

assets

Create each file as required. See Best Practices for Creating Themes for details.

Important:
To avoid file name collisions, do not create new files or folders that share the same name, even if they reside in different locations.
Save each new file in the correct location within your directory structure.

For this example, you want to add a new Sass file titled _newSass.scss. As a best practice, save this file in the following location:

Workspace/<THEME_DIRECTORY>/Modules/BaseSassStyles/Sass/reference-theme/_newSass.scss
Open the theme’s manifest.json file.

For example:

Workspace/<THEME_DIRECTORY>/manifest.json
Include your new file or files in the appropriate location as required:
- If adding a template, list the file by application. Include the .tpl file in the files array of the appropriate application object (Shopping, MyAccount, or Checkout). When declaring your new file, include the path to the correct module. The order of your declaration does not matter.
  
  For example:
```
                    //...
"templates": {
   "application": {
      "shopping": {
         "files": [
            //...
         ]
      }
   }
//... 

                  
```
- If adding a Sass file, list the .scss file in the files array of the sass object. You set up the Sass entry point in a later step. When declaring your new file, include the path to the correct module. Add this line in a location that makes the most semantic sense within the Sass hierarchy. For example:
```
                    //...
"sass": {
   "entry_points": {
      "shopping": "Modules/Shopping/shopping.scss",
      "myaccount": "Modules/MyAccount/myaccount.scss",
      "checkout": "Modules/Checkout/checkout.scss"
   }
   "files": [
      //...
   ]
}
//... 

                  
```
- If adding an asset, add your asset as part of the files array of the img, font-awesome, or font object, as appropriate. When declaring your new file, include the path to the correct folder (img/, font-awesome/, or font/). The order of your declaration does not matter. For example:
```
                    //...
"assets": {
   "img": {
      "files": [
         //...
      ]
   }
   "font-awesome": {
      "files": [
         //...
      ]
   }
}
//... 

                  
```
This ensures that the compiler includes your customizations. In this example, you are adding a Sass file. Therefore, you add _newSass.scss as a dependency to the files array of the sass object.

Your manifest file might look similar to the following example:
```
                "sass": {
   "entry_points": {
      "shopping": "Modules/Shopping/shopping.scss",
      "myaccount": "Modules/MyAccount/myaccount.scss",
      "checkout": "Modules/Checkout/checkout.scss"
   }
   "files": [
      //...
      "Modules/BaseSassStyles@x.y.z/Sass/reference-theme/_newSass.scss",
      //... 

              
```
Save the manifest.json file.

If your new file is an asset or template, you have no further action required. However, if your new file is a Sass file, follow these additional steps:

Identify the application or applications impacted by your new Sass file.

Edit the application entry point file to include the same dependency you introduced in the manifest file.

Application Impacted	Application Entry Point
Shopping	Modules/Shopping/shopping.scss
My Account	Modules/MyAccount/myaccount.scss
Checkout	Modules/Checkout/checkout.scss

Application Impacted

Application Entry Point

Shopping

Modules/Shopping/shopping.scss

My Account

Modules/MyAccount/myaccount.scss

Checkout

Modules/Checkout/checkout.scss

In this example, the Cart module impacts the Shopping application. Therefore, you open the Shopping entry point file and include the dependency. Your Shopping.scss file should look similar to the following example:

                    //...
@import "../BaseSassStyles@x.y.z/Sass/reference-theme/newSass";   
//...

Just as you did in the manifest.json file, place this file in a location that makes semantic sense within the Sass hierarchy you are customizing.

Save the application Sass file.

Next Steps

When you are ready, use the theme developer tools to test or deploy your theme. See Test and Deploy Your Theme for details.

To learn about additional capabilities offered with themes, see Do More With Themes.

For guidance about how best to customize your themes, see:

To create a new file for a theme:

Next Steps

Related Topics