2.59 kBMarkdownView Raw
1# @stencil/sass
2
3This 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
6First, npm install within the project:
7
8```
9npm install @stencil/sass --save-dev
10```
11
12Next, 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
16import { Config } from '@stencil/core';
17import { sass } from '@stencil/sass';
18
19export const config: Config = {
20 plugins: [
21 sass()
22 ]
23};
24```
25
26During development, this plugin will kick-in for `.scss` or `.sass` style urls, and precompile them to CSS.
27
28
29## Options
30
31Sass 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
36The `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
39exports.config = {
40 plugins: [
41 sass({
42 injectGlobalPaths: [
43 'src/globals/variables.scss',
44 'src/globals/mixins.scss'
45 ]
46 })
47 ]
48};
49```
50
51Note 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
65Please 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