Installation

Install the bundle:

1

$ composer require symfonycasts/sass-bundle

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!

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-sass

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

The main option is root_sass option, which defaults to assets/styles/app.scss. This represents the source Sass file.

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'