1 | # @stencil/sass
|
2 |
|
3 | This package is used to easily precompile Sass files within Stencil components. Internally this plugin uses a pure JavaScript implementation of [Sass](https://www.npmjs.com/package/sass). Please see the
|
4 | [Behavioral Differences from Ruby Sass](https://www.npmjs.com/package/sass#behavioral-differences-from-ruby-sass) doc if issues have surfaced since upgrading from previous versions which used used the `node-sass` implementation.
|
5 |
|
6 | First, npm install within the project:
|
7 |
|
8 | ```
|
9 | npm install @stencil/sass --save-dev
|
10 | ```
|
11 |
|
12 | Next, within the project's stencil config, import the plugin and add it to the config's `plugins` property:
|
13 |
|
14 | #### stencil.config.ts
|
15 | ```ts
|
16 | import { Config } from '@stencil/core';
|
17 | import { sass } from '@stencil/sass';
|
18 |
|
19 | export const config: Config = {
|
20 | plugins: [
|
21 | sass()
|
22 | ]
|
23 | };
|
24 | ```
|
25 |
|
26 | During development, this plugin will kick-in for `.scss` or `.sass` style urls, and precompile them to CSS.
|
27 |
|
28 |
|
29 | ## Options
|
30 |
|
31 | Sass options can be passed to the plugin within the stencil config, which are used directly by `sass`. Please reference [sass documentation](https://www.npmjs.com/package/sass) for all available options. Note that this plugin automatically adds the component's directory to the `includePaths` array.
|
32 |
|
33 |
|
34 | ### Inject Globals Sass Paths
|
35 |
|
36 | The `injectGlobalPaths` config is an array of paths that automatically get added as `@import` declarations to all components. This can be useful to inject Sass variables, mixins and functions to override defaults of external collections. For example, apps can override default Sass variables of [Ionic components](https://www.npmjs.com/package/@ionic/core). Relative paths within `injectGlobalPaths` should be relative to the stencil config file.
|
37 |
|
38 | ```js
|
39 | exports.config = {
|
40 | plugins: [
|
41 | sass({
|
42 | injectGlobalPaths: [
|
43 | 'src/globals/variables.scss',
|
44 | 'src/globals/mixins.scss'
|
45 | ]
|
46 | })
|
47 | ]
|
48 | };
|
49 | ```
|
50 |
|
51 | Note that each of these files are always added to each component, so in most cases they shouldn't contain CSS because it'll get duplicated in each component. Instead, `injectGlobalPaths` should only be used for Sass variables, mixins and functions, but does not contain any CSS.
|
52 |
|
53 |
|
54 | ## Related
|
55 |
|
56 | * [sass](https://www.npmjs.com/package/sass)
|
57 | * [Stencil](https://stenciljs.com/)
|
58 | * [Ionic Discord](https://chat.stenciljs.com/)
|
59 | * [Ionic Components](https://www.npmjs.com/package/@ionic/core)
|
60 | * [Ionicons](http://ionicons.com/)
|
61 |
|
62 |
|
63 | ## Contributing
|
64 |
|
65 | Please see our [Contributor Code of Conduct](https://github.com/ionic-team/ionic/blob/master/CODE_OF_CONDUCT.md) for information on our rules of conduct. |
\ | No newline at end of file |