Sass For Symfony!
Edit this pageThis bundle makes it easy to use Sass with Symfony's AssetMapper Component (no Node required!).
- Automatically downloads the correct Sass binary
- Adds a
sass:build
command to build and watch your Sass changes
Tip
While this bundle is great, you may not need to use Sass! Native CSS now supports variables and nesting. See Is it time to drop Sass? article for some more details.
Usage
Start by writing your first Sass file assets/styles/app.scss
, and let's add some basic style
1 2 3 4 5 6 7
/* assets/styles/app.scss */
$red: #fc030b;
body {
background: $red;
}
Then point your styles in your template
1 2 3 4 5
{# templates/base.html.twig #}
{% block stylesheets %}
<link rel="stylesheet" href="{{ asset('styles/app.scss') }}">
{% endblock %}
That's right! You point directly to the .scss
file. But don't worry, the final built .css
file will be returned!
Then run the command:
1
$ php bin/console sass:build --watch
And that's it!
Symfony CLI
If using the Symfony CLI, you can add the build
command as a worker
to be started whenever you run symfony server:start
:
1 2 3 4 5
# .symfony.local.yaml
workers:
# ...
sass:
cmd: ['symfony', 'console', 'sass:build', '--watch']
Tip
If running symfony server:start
as a daemon, you can run
symfony server:log
to tail the output of the worker.
How Does it Work?
The first time you run one of the Sass commands, the bundle will download the correct Sass binary for your system into the bin/dart-sass
directory.
When you run sass:build
, that binary is used to compile Sass files into a var/sass/app.built.css
file. Finally, when the contents of assets/styles/app.scss
are requested, the bundle swaps the contents of that file with the contents of var/sass/app.built.css
. Nice!
Excluding Sass Files from AssetMapper
Because you have .scss
files in your assets/
directory, when you deploy, these
source files will be copied into the public/assets/
directory. To prevent that,
you can exclude them from asset mapper:
1 2 3 4 5 6 7 8
# config/packages/asset_mapper.yaml
framework:
asset_mapper:
paths:
- assets/
excluded_patterns:
- '*/assets/styles/_*.scss'
- '*/assets/styles/**/_*.scss'
Note
Be sure not to exclude your main SCSS file (e.g. assets/styles/app.scss
):
this is used in AssetMapper and its contents are swapped for the final, built CSS.
Using Bootstrap Sass
Bootstrap is available as Sass, allowing you to customize the look and feel of your app. An easy way to get the source Sass files is via a Composer package:
1
$ composer require twbs/bootstrap
Now, import the core bootstrap.scss
from your app.scss
file:
1 2 3 4
/* Override some Bootstrap variables */
$red: #FB4040;
@import '../../vendor/twbs/bootstrap/scss/bootstrap';
Deploying
When you deploy, run sass:build
command before the asset-map:compile
command so the built file is available:
1 2
$ php bin/console sass:build
$ php bin/console asset-map:compile
Limitation: url()
Relative Paths
When using url()
inside a Sass file, currently, the path must be relative to the root .scss
file. For example, suppose the root .scss
file is:
1 2
/* assets/styles/app.scss */
import 'tools/base';
Assume there is an assets/images/login-bg.png
file that you want to refer to from base.css
:
1 2 3 4 5 6 7 8
/* assets/styles/tools/base.scss */
.splash {
/* This SHOULD work, but doesn't */
background-image: url('../../images/login-bg.png');
/* This DOES work: it's relative to app.scss */
background-image: url('../images/login-bg.png');
}
It should be possible to use url()
with a path relative to the current file. However, that is not currently possible. See this issue for more details.
Configuration
To see the full config from this bundle, run:
1
$ php bin/console config:dump symfonycasts_sass
Source Sass file
The main option is root_sass
option, which defaults to assets/styles/app.scss
. This represents the source Sass file.
1 2 3
# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
root_sass: 'assets/styles/app.scss'
Note
The root_sass
option also supports an array of paths that represents different source Sass files:
1 2 3
symfonycasts_sass:
root_sass:
- '%kernel.project_dir%/assets/scss/app.scss'
Sass CLI Options
You can configure most of the Dart Sass CLI options:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
sass_options:
# The output style for the compiled CSS files: expanded or compressed. Defaults to expanded.
# style: expanded
# Emit a @charset or BOM for CSS with non-ASCII characters. Defaults to true in Dart Sass.
# charset: true
# Wether to generate source maps. Defaults to true when "kernel.debug" is true.
# source_map: true
# Embed source file contents in source maps. Defaults to false.
# embed_sources:
# Embed source map contents in CSS. Defaults to false.
# embed_source_map:
# Don't print warnings. Defaults to false.
# quiet:
# Don't print deprecated warnings for dependencies. Defaults to false.
# quiet_deps:
# Don't compile more files once an error is encountered. Defaults to false.
# stop_on_error:
# Print full Dart stack traces for exceptions. Defaults to false.
# trace:
Using a different binary
This bundle already installed for you the right binary. However, if you already have a binary installed on your machine you can instruct the bundle to use that binary, set the binary
option:
1 2
symfonycasts_sass:
binary: 'node_modules/.bin/sass'