gremo/assetic-extra

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

assetic-extra

, _(*1)

A collection of extra assetic resources to use with Symfony AsseticBundle., _(*2)

Table of Contents

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

Installation

Install this library using Composer:, _(*3)

composer require gremo/assetic-extra

Filters

Note: with Symfony 3.3 you can replace %kernel.root_dir%/.. with %kernel.project_dir% for filters configuration., _(*4)

The following extra filters can be configured and used in your templates., _(*5)

Babel

JavaScript transpiler for node.js (https://babeljs.io)., _(*6)

Configuration, _(*7)

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

Options (reference), _(*8)

• 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., _(*9)

Usage, _(*10)

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

Browserify

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

Credits goes to the original author (https://github.com/kriswallsmith/assetic/pull/669), I changed it a bit and added trasforms support., _(*12)

Configuration, _(*13)

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

Options, _(*14)

• 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, _(*15)

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., _(*16)

{% 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., _(*17)

Example of main.js:, _(*18)

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

Example of modules/module1.js:, _(*19)

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

CSSO

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

Configuration, _(*21)

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

Options (reference), _(*22)

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

Usage, _(*23)

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

Tip: fast and safe options, _(*24)

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

PostCSS

A tool for transforming CSS with JavaScript (http://postcss.org)., _(*25)

Configuration, _(*26)

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

Options (reference), _(*27)

• 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, _(*28)

{% 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)., _(*29)

Configuration, _(*30)

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

Options (reference), _(*31)

• 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, _(*32)

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

Tip: Boostrap 4, _(*33)

Use this options for Bootstrap 4 (see package.json):, _(*34)

nodesass:
    # ...
    precision: 6

Tip: source maps, _(*35)

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:, _(*36)

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., _(*37)

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:, _(*38)

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

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