Sass For Symfony!

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!

1
2
3
4
5

# .symfony.local.yaml
workers:
    # ...
    sass:
        cmd: ['symfony', 'console', 'sass:build', '--watch']

How Does it Work?

The first time you run one of the Sass commands, the bundle will automatically try to detect the correct Sass binary installed in the system and use it. If the binary is not found, the bundle will automatically download the correct one for your system and put it 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 AssetMapper:

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'

How to Get Source Sass Files for 3rd-Party Libraries

The easiest way to get 3rd-party Sass files is via Composer. For example, see the section below to know how to get the source Sass files for Bootstrap.

But if you're using a library that isn't available via Composer, you’ll need to either download it to your app manually or grab it via NPM.

1

$ composer require twbs/bootstrap

1
2
3
4

/* Override some Bootstrap variables */
$red: #FB4040;

@import '../../vendor/twbs/bootstrap/scss/bootstrap';

1

$ composer require thomaspark/bootswatch

1
2
3

@import '../../vendor/thomaspark/bootswatch/dist/[theme]/variables';
@import '../../vendor/twbs/bootstrap/scss/bootstrap';
@import '../../vendor/thomaspark/bootswatch/dist/[theme]/bootswatch';

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

1
2
3

# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    root_sass: 'assets/styles/app.scss'

1
2
3

symfonycasts_sass:
    root_sass:
        - '%kernel.project_dir%/assets/scss/app.scss'

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
30
31
32

# 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

        # Register additional load paths. Defaults to empty array.
        # load_path: []

        # Whether 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 has already detected or installed for you the right binary. However, if you already have a binary installed on your machine and somehow the bundle has not been able to find it automatically - you can instruct the bundle to use that binary, set the binary option:

1
2

symfonycasts_sass:
    binary: 'node_modules/.bin/sass'

Register Additional Load Paths

You can provide additional load paths to resolve modules with the load_path option.

For example, an alternative way to use Bootstrap would be to register the vendor path:

1
2
3
4
5

# config/packages/symfonycasts_sass.yaml
symfonycasts_sass:
    sass_options:
        load_path:
            - '%kernel.project_dir%/vendor/twbs/bootstrap/scss'

And then import bootstrap from app.scss with:

1

@import 'bootstrap';