@@ -33,40 +33,80 @@ The current version of `dartsass-sprockets` supports:
33
33
34
34
For older versions of Ruby and Rails may be supported with earlier versions of this gem.
35
35
36
- ### Upgrading to Dart Sass
36
+ ## CSS Minification (Production)
37
37
38
- This gem is a drop-in replacement to [ sass-rails ] ( https://github.com/rails/sass-rails ) .
39
- Note the following differences :
38
+ This gem uses a Railtie to automatically set the following
39
+ configuration in all environments * except * Development :
40
40
41
- * This library does not apply SASS processing to ` .css ` files. Please ensure all your SASS files have file extension ` .scss ` .
42
- * ` config.sass.style ` values ` :nested ` and ` :compact ` will behave as ` :expanded ` . Use ` :compressed ` for minification.
43
- * ` config.sass.line_comments ` option is ignored and will always be disabled.
41
+ ``` ruby
42
+ # set automatically by this gem
43
+ config.assets.css_compressor = :sass
44
+ ```
44
45
45
- ## Inline Source Maps
46
+ This causes Sprockets to minify * all* CSS assets (both Sass and plain CSS) using Dart Sass.
47
+ This minification is done as a * second-pass* after compiling the Sass to CSS,
48
+ and is done irrespective of whether the ` config.sass.style ` option is set to ` :compressed ` .
49
+ To disable this behavior, set ` config.assets.css_compressor = false ` .
50
+
51
+ ## Source Maps (Development)
46
52
47
53
To turn on inline source maps, add the following configuration
48
- to your ` development.rb ` file:
54
+ to your ` config/environments/ development.rb` file:
49
55
50
56
``` ruby
51
- # config/environments/development.rb
57
+ # in config/environments/development.rb
52
58
config.sass.inline_source_maps = true
53
59
```
54
60
55
- After adding this config line, you may need to clear your assets cache
56
- (` rm -r tmp/cache/assets ` ), stop Spring, and restart your Rails server.
57
-
58
- Note these source maps are * inline* and will be appended to the compiled
59
- ` application.css ` file. (They will * not* generate additional files.)
61
+ Note these source maps appended * inline* to the compiled ` application.css ` file.
62
+ (This option will * not* generate additional files.)
60
63
61
- ## Silencing Deprecation Warnings That Come From Dependencies
64
+ ## Silencing Deprecation Warnings
62
65
63
- To silence deprecation warnings during compilation that come from dependencies, add the following configuration to your ` application.rb ` file:
66
+ To silence common deprecation warnings, add the following
67
+ configuration. Refer to details in the below section.
64
68
65
69
``` ruby
66
- # config/environments/development .rb
70
+ # in config/application .rb
67
71
config.sass.quiet_deps = true
72
+ config.sass.silence_deprecations = [' import' ]
68
73
```
69
74
75
+ ## Advanced Configuration
76
+
77
+ The following options are exposed via ` Rails.application.config.sass.{option} ` .
78
+ Options denoted with * are handed by the sass-embedded gem and passed into Dart Sass;
79
+ refer to [ the sass-embedded documentation] ( https://rubydoc.info/gems/sass-embedded/Sass )
80
+ and the [ Dart Sass documentation] ( https://sass-lang.com/documentation/js-api/interfaces/options/ ) .
81
+
82
+ | Option | Type | Description |
83
+ | -------------------------| -----------------| -------------------------------------------------------------------------------------------------------------------------------|
84
+ | ` load_paths ` | ` Array<String> ` | Additional paths to look for imported files. |
85
+ | ` inline_source_maps ` | ` Boolean ` | If ` true ` , will append source maps inline to the generated CSS file. Refer to section below. |
86
+ | ` style ` * | ` Symbol ` | ` :expanded ` (default) or ` :compressed ` . See note about CSS Minification below. |
87
+ | ` charset ` * | ` Boolean ` | Whether to include a @charset declaration or byte-order mark in the CSS output (default ` true ` ). |
88
+ | ` logger ` * | ` Object ` | An object to use to handle warnings and/or debug messages from Sass. |
89
+ | ` alert_ascii ` * | ` Boolean ` | If ` true ` , Dart Sass will exclusively use ASCII characters in its error and warning messages (default ` false ` ). |
90
+ | ` alert_color ` * | ` Boolean ` | If ` true ` , Dart Sass will use ANSI color escape codes in its error and warning messages (default ` false ` ). |
91
+ | ` verbose ` * | ` Boolean ` | By default (` false ` ) Dart Sass logs up to five occurrences of each deprecation warning. Setting to ` true ` removes this limit. |
92
+ | ` quiet_deps ` * | ` Boolean ` | If ` true ` , Dart Sass won’t print warnings that are caused by dependencies (default ` false ` ). |
93
+ | ` silence_deprecations ` * | ` Array<String> ` | An array of active deprecations to ignore. Refer to (deprecations)[ dartsass-deprecations] . |
94
+ | ` fatal_deprecations ` * | ` Array<String> ` | An array of deprecations to treat as fatal. Refer to (deprecations)[ dartsass-deprecations] . |
95
+ | ` future_deprecations ` * | ` Array<String> ` | An array of future deprecations to opt-into early. Refer to (deprecations)[ dartsass-deprecations] . |
96
+ | ` importers ` * | ` Array<Object> ` | Custom importers to use when resolving ` @import ` directives. |
97
+
98
+ When changing config options in Development environment, you may need to clear
99
+ your assets cache (` rm -r tmp/cache/assets ` ) and restart your Rails server.
100
+
101
+ ### Upgrading from Legacy Sass Rails
102
+
103
+ This gem is a drop-in replacement to [ sass-rails] ( https://github.com/rails/sass-rails ) .
104
+ Note the following differences:
105
+
106
+ * This library does not apply SASS processing to ` .css ` files. Please ensure all your SASS files have file extension ` .scss ` .
107
+ * ` config.sass.style ` values ` :nested ` and ` :compact ` will behave as ` :expanded ` . Use ` :compressed ` for minification.
108
+ * ` config.sass.line_comments ` option is ignored and will always be disabled.
109
+
70
110
## Alternatives
71
111
72
112
* [ dartsass-rails] ( https://github.com/rails/dartsass-rails ) : The Rails organization
@@ -89,3 +129,5 @@ config.sass.quiet_deps = true
89
129
3 . Commit your changes (` git commit -am 'Add some feature' ` ) - try to include tests
90
130
4 . Push to the branch (` git push origin my-new-feature ` )
91
131
5 . Create a new Pull Request
132
+
133
+ [ dartsass-deprecations ] : https://github.com/sass/sass/blob/40c50cb/js-api-doc/deprecations.d.ts#L260
0 commit comments