assetic-extra

A collection of extra assetic resources to use with Symfony AsseticBundle.

Table of Contents

• Filters
  • Babel
  • Browserify
  • CSSO
  • PostCSS
  • Node-sass
• Recipes

Installation

Install this library using Composer:

composer require gremo/assetic-extra

Filters

Note: with Symfony 3.3 you can replace %kernel.root_dir%/.. with %kernel.project_dir% for filters configuration.

The following extra filters can be configured and used in your templates.

Babel

JavaScript transpiler for node.js (https://babeljs.io).

Configuration

assetic:
    # ...
    babeljs:
        resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/babeljs.xml'
        # options here

Options (reference)

• bin: path to your babel binary (default: /usr/bin/babel)
• retain_lines
• presets: a string or array of presets to use (preset name if installed globally, path otherwise)
• plugins: a string or array of plugins to use (plugin name if installed globally, path otherwise)
• compact
• minified
• no_babel_rc
• auxiliary_comment_before
• auxiliary_comment_after
• parser_opts
• generator_opts

Note: Babel will look for .babelrc file in current asset directory and will travel up the directory tree (see Lookup behavior), unless you specify the no_babel_rc option. This means you can put your .babelrc file in your project root without cluttering your config.yml.

Usage

{% javascripts '../app/Resources/js/*.js' filter='babeljs' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

Browserify

Lets you require('modules') in the browser (http://browserify.org).

Credits goes to the original author (kriswallsmith/assetic#669), I changed it a bit and added trasforms support.

Configuration

assetic:
    # ...
    browserify:
        resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/browserify.xml'
        # options here

Options

• bin: path to your browserify binary (default: /usr/bin/browserify)
• node: path to your node binary (default: %assetic.node.bin%, set to null to use browserify binary instead)
• node_paths: paths to add to Node.js environment when using node option (default: %assetic.node.paths%)
• transforms a string or array of Browserify transform to apply

Usage

Note: there is no need to combine assets (modules/module1.js in the example) as long as you require your module. Browserify filter will take care of combining them in the output file.

{% javascripts '../app/Resources/js/main.js' filter='browserify' %}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

Note: the assetic:watch command will regenerate the assets only if you change the "main" script. Modules changes will not be monitored as they are not included in the javascripts tag.

Example of main.js:

// main.js
require('./modules/module1.js');
console.log('main.js');

Example of modules/module1.js:

// modules/module1.js
console.log('modules/module1.js');

CSSO

CSSO (CSS Optimizer) is a CSS minifier (https://github.com/css/csso).

Configuration

assetic:
    # ...
    csso:
        resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/csso.xml'
        # options here

Options (reference)

• bin: path to your csso binary (default: /usr/bin/csso)
• comments
• force_media_merge
• restructure_off
• usage

Usage

{% stylesheets '../app/Resources/css/*' filter='csso' %}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}

Tip: fast and safe options

csso:
    # ...
    comments: none
    restructure_off: true

PostCSS

A tool for transforming CSS with JavaScript (http://postcss.org).

Configuration

assetic:
    # ...
    postcss:
        resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/postcss.xml'
        # options here

Options (reference)

• bin: path to your postcss binary (default: /usr/bin/postcss)
• no_map: disable the default inline sourcemaps
• use: list of postcss plugins to use
• parser: custom postcss parser
• stringifier: custom postcss stringifier
• syntax: custom postcss syntax
• config: set a custom path to look for a config file

Usage

{% stylesheets '../app/Resources/css/*' filter='postcss' %}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}

Node-sass

Parses SASS/SCSS into CSS using the LibSass bindings for node.js (https://github.com/sass/node-sass).

Configuration

assetic:
    # ...
    nodesass:
        resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/nodesass.xml'
        # options here

Options (reference)

• bin: path to your node-sass binary (default: /usr/bin/node-sass)
• import_paths
• indent_type
• indent_width
• linefeed
• output_style
• precision
• source_comments
• source_map_location
• source_map_public_dir

Usage

{% stylesheets '../app/Resources/scss/style.scss' filter='nodesass' %}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}

Tip: Boostrap 4

Use this options for Bootstrap 4 (see package.json):

nodesass:
    # ...
    precision: 6

Tip: source maps

In order to generate the source maps, you'll need to specify a public accessible directory where the .map files can be placed (source_map_location) together with the base path (source_map_public_dir) which will be used when generating the urls to the mapping files:

nodesass:
    # ...
    source_map_location: '%kernel.root_dir%/../web/assets/maps'
    source_map_public_dir: '/assets/maps'

Recipes

ES6 modules with Browserify

Write ES6 JavaScript modules using import/export style and make it work in the browser.

Problem: Browserify filter transform your source file and not your transpiled one, so it would fail at the first import or export keyword. Solution: only use the browserify filter with babelify transform filter configuration:

Note if Browserify cannot find the babelify module, try installing it locally in your project folder and use the absolute path.

browserify:
    resource: '%kernel.root_dir%/../vendor/gremo/assetic-extra/Resources/filter/browserify.xml'
    transforms:
        - '[ babelify --presets env ]'