Using Asset Sets to Manage Themes & Styles

NOTE: This article assumes familiarity with running Knapsack locally.

Introduction to Asset Sets

Asset sets provide a method of managing theme or style variations for your patterns in Knapsack and in your production applications. Patterns and components in your workspace can have multiple asset sets, allowing users to quickly swap between different versions. For example, you could use asset sets to manage brands, color schemes, dark vs. light mode, or any other collection of styling you want to enable across your patterns.

Each asset set is a collection of CSS and Javascript files that determine how your components look and behave. When you add an asset set to a given component, all templates in that component are affected, allowing you to apply fundamental changes without updating each template manually.

Creating Asset Sets

Create an asset set in your workspace to apply it to your patterns. 

Note: Before you create an asset set, check that your CSS and Javascript files are compiled and located in the ks-public/dist folder of your Knapsack repository.

1. In the data folder of your Knapsack repository, open knapsack.asset-sets.json.
2. Add a new asset set under allAssetSets using the following formatting.

“asset-set”: {
	“id”: “asset-id”,
	“title”: “asset-title”,
	"inlineJs": "inline-javascript",
	“assets”: [
		{ “src”: “file1” },
		{ “src”: “file2” },
		{ “src”: “file3” },
		{ ... }
	]
}

Where:

• asset-set is the name for the new asset set.
• asset-id is the id you use to assign the asset set to patterns.
• asset-title is the display name you see in your workspace.
• inline-javascript is a single line of Javascript that you can use to select themes or other body classes from your styles.
• file# is the relative path to the Javascript or CSS file you want the asset set to reference. If your asset is hosted on a content delivery network (CDN), you can provide the URL to the asset here.
3. Save knapsack.asset-sets.json.

Apply asset sets to patterns

Now that you’ve created an asset set in your workspace, you must apply the asset set before you see it in the UI. 

You can apply the asset set globally to all patterns or to individual patterns.

Apply an asset set globally

Adding an asset set to the global list applies it to every pattern in your workspace.

Note: Global asset sets do not apply to patterns that have a value for assetSetIds in the pattern’s JSON file. If you want your asset set to also apply to these patterns, you must either add the asset set to those patterns or remove assetSetIds from those patterns.

1. In the data folder of your Knapsack repository, open knapsack.asset-sets.json.
2. Add the id for your asset set to the globalAssetSetIds array.
3. Save knapsack.asset-sets.json.
4. Restart the Knapsack workspace.

Now, your pattern pages have a drop down menu containing the asset set.

Apply an asset set to a single pattern

Applying an asset set to an individual pattern adds it to only one pattern. 

Note: When you apply an asset set to a single pattern, that pattern no longer uses global asset sets. If you want the global asset sets to apply to the pattern, you can add those asset sets to the pattern’s JSON file.

1. In the data folder of your Knapsack repository, open the pattern’s JSON file.
2. If the assetSetIds array does not already exist, add it to the JSON file.
3. Add the ID of the asset set to the assetSetIds array.
4. Save knapsack.asset-sets.json.