Flask-Assets

Flask-Assets helps you to integrate webassets into your Flask application.

Installation

Install the extension with one of the following commands:

$ easy_install Flask-Assets

or alternatively if you have pip installed:

$ pip install Flask-Assets

Usage

You initialize the app by creating an Environment instance, and registering your assets with it in the form of so called bundles.

from flask import Flask
from flask.ext.assets import Environment, Bundle

app = Flask(__name__)
assets = Environment(app)

js = Bundle('jquery.js', 'base.js', 'widgets.js',
            filters='jsmin', output='gen/packed.js')
assets.register('js_all', js)

A bundle consists of any number of source files (it may also contain other nested bundles), an output target, and a list of filters to apply.

All paths are relative to your app’s static directory, or the static directory of a Flask blueprint.

If you prefer you can of course just as well define your assets in an external config file, and read them from there. webassets includes a number of helper classes for some popular formats like YAML.

Like is common for a Flask extension, a Flask-Asssets instance may be used with multiple applications by initializing through init_app calls, rather than passing a fixed application object:

app = Flask(__name__)
assets = flask.ext.assets.Environment()
assets.init_app(app)

Using the bundles

Now with your assets properly defined, you want to merge and minify them, and include a link to the compressed result in your web page:

{% assets "js_all" %}
    <script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}

That’s it, really. Flask-Assets will automatically merge and compress your bundle’s source files the first time the template is rendered, and will automatically update the compressed file everytime a source file changes. If you set ASSETS_DEBUG in your app configuration to True, then each source file will be outputted individually instead.

Flask blueprints

If you are using Flask blueprints, you can refer to a blueprint’s static files via a prefix, in the same way as Flask allows you to reference a blueprint’s templates:

js = Bundle('app_level.js', 'blueprint/blueprint_level.js')

In the example above, the bundle would reference two files, {APP_ROOT}/static/app_level.js, and {BLUEPRINT_ROOT}/static/blueprint_level.js.

If you have used the webassets library standalone before, you may be familiar with the requirement to set the directory and url configuration values. You will note that this is not required here, as Flask’s static folder support is used instead. However, note that you can set a custom root directory or url if you prefer, for some reason. However, in this case the blueprint support of Flask-Assets is disabled, that is, referencing static files in different blueprints using a prefix, as described above, is no longer possible. All paths will be considered relative to the directory and url you specified.

Pre 0.7 modules are also supported; they work exactly the same way.

Templates only

If you prefer, you can also do without defining your bundles in code, and simply define everything inside your template:

{% assets filters="jsmin", output="gen/packed.js",
          "common/jquery.js", "site/base.js", "site/widgets.js" %}
    <script type="text/javascript" src="{{ ASSET_URL }}"></script>
{% endassets %}

Configuration

webassets supports a couple of configuration options. Those can be set both through the Environment instance, as well as the Flask configuration. The following two statements are equivalent:

assets_env.debug = True
app.config['ASSETS_DEBUG'] = True

For a list of available settings, see the full webassets documentation.

Babel Configuration

If you use Babel for internationalization, then you will need to add the extension to your babel configuration file as webassets.ext.jinja2.AssetsExtension

Otherwise, babel will not extract strings from any templates that include an assets tag.

Here is an example babel.cfg:

[python: **.py]
[jinja2: **.html]
extensions=jinja2.ext.autoescape,jinja2.ext.with_,webassets.ext.jinja2.AssetsExtension

Flask-S3 Configuration

Flask-S3 allows you to upload and serve your static files from an Amazon S3 bucket. It accomplishes this by overwriting the Flask url_for function. In order for Flask-Assets to use this overwritten url_for function, you need to let it know that you are using Flask-S3. Just set

app.config['FLASK_ASSETS_USE_S3']=True

Flask-CDN Configuration

Flask-CDN allows you to upload and serve your static files from a CDN (like Amazon Cloudfront), without having to modify your templates. It accomplishes this by overwriting the Flask url_for function. In order for Flask-Assets to use this overwritten url_for function, you need to let it know that you are using Flask-CDN. Just set

app.config['FLASK_ASSETS_USE_CDN']=True

Management Command

If you have Flask-Script installed, then a command will be available as flaskext.assets.ManageAssets:

from flask.ext.assets import ManageAssets
manager = Manager(app)
manager.add_command("assets", ManageAssets(assets_env))

You can explicitly pass the assets_env when adding the command as above. Alternatively, ManageAssets will import the current_app from Flask and use the jinja_env.

The command allows you to do things like rebuilding bundles from the command line. See the list of available subcommands.

Webassets documentation

For further information, have a look at the complete webassets documentation, and in particular, the following topics:

  • Configuration
  • All about bundles
  • Builtin filters
  • Custom filters
  • CSS compilers
  • FAQ
Fork me on GitHub