terra-toolkit
Version:
Utilities to help when developing terra modules.
128 lines (99 loc) • 5.01 kB
Markdown
Terra Toolkit provides a built-in mechanism for aggregating themes.
By default, the terra-toolkit webpack configuration enables theme aggregation when it detects the presence of a `terra-theme.config.js` file.
Create a new file within the same directory as your webpack configuration file.
The file must be named `terra-theme.config.js`.
```
project
├── terra-theme.config.js
├── webpack.config.js
```
Within this file declare and export an object containing your theme configuration.
Theme aggregation uses this configuration to search for theme files within the following directory format: `themes->theme-name->theme-name.scss`. Then, for each theme, a root and/or scope themes will be generated.
The generated file(s) output to the `generated-themes` directory and are imported into `aggregated-themes.js`. This js file will be automatically included as an entry point within your application if you are using the webpack configuration provided by terra-toolkit.
### Sample Project Structure
```txt
project
├── node_modules
│ └── terra-component
│ └── themes
│ ├── terra-dark-theme
│ │ └── terra-dark-theme.scss
│ └── terra-light-theme
│ └── terra-light-theme.scss
└── themes
└── terra-dark-theme
├── component-1.scss
├── component-2.scss
└── terra-dark-theme.scss
```
*Note*: To support previous functionality, if a project contains existing `root.scss` or `scoped.scss` theme files within namespaced theme directories, terra-toolkit will aggregate those theme files first, then generate theme files second. The CSS import order follows this pattern - existing `root.scss` or `scoped.scss` theme files are imported first, then generated theme files are subsequently imported.
In summary, because of CSS import order, generated theme files will take precedence over existing `root.scss` or `scoped.scss` theme files. Toolkit will default to theme generation on the 6.0 release. Below is an example.
```scss
import 'orion-fusion-theme/src/scss/root-theme.scss'; // Existing root theme
import './root-orion-fusion-theme.scss'; // Generated theme file. Takes precedence because it is imported after existing root theme.
```
```js
const themeConfig = {
exclude: [], // Files to exclude. Accepts glob patterns.
theme: 'terra-dark-theme', // The default theme.
scoped: ['terra-light-theme', 'terra-lowlight-theme'], // An array of scoped themes.
};
module.exports = themeConfig;
```
The `exclude` option accepts an array of files to exclude from being aggregated.
The `theme` option accepts the string name of a default theme. The default theme will be applied directly to the application.
The `scoped` option accepts an array of theme names to generate or aggregate.
This example follows the [sample project structure](
`theme-name` files should contain imports or CSS custom property values encased in a `:global` scope.
```scss
:global {
@import 'component-1';
@import 'component-2';
}
```
Using the above `terra-theme-config` in conjunction with the above project structure generates:
```scss
:root {
@import '../node_modules/terra-component/themes/terra-dark-theme/terra-dark-theme.scss';
@import '../themes/terra-dark-theme/terra-dark-theme.scss';
}
```
```scss
.light-theme {
@import '../node_modules/terra-component/themes/terra-light-theme/theme-variables.scss';
}
```
```scss
import './root-terra-dark-theme.scss';
import './scoped-terra-light-theme.scss';
```
Theme files must follow naming conventions to be aggregated - theme aggregation will search for `root` or `scope` theme files. These theme files are expected be within a namespaced directory within a `themes` directory.
Aggregated themes will be imported into a single `aggregated-themes.js` file inside a `generated-themes` directory. This file will be automatically included as an entry point within your application if you are using the webpack configuration provided by terra-toolkit.
*Note*: This functionality will be deprecated on 6.0 release.
```txt
project
└── themes
├── terra-dark-theme
│ ├── component.scss
│ ├── root-theme.scss
│ └── scoped-theme.scss
└── terra-light-theme
├── component.scss
├── root-theme.scss
└── scoped-theme.scss
```