README

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

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 (https://github.com/kriswallsmith/assetic/pull/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 ]'

gremo / assetic-extra

Maintainers

Details

README

Table of Contents

Installation

Filters

Babel

Browserify

CSSO

PostCSS

Node-sass

Recipes

ES6 modules with Browserify