index.rst

Using webassets in standalone mode

You don't need to use one of the frameworks into which webassets can integrate. Using the underlying facilities directly is almost as easy.

And depending on what libraries you use, there may still be some things webassets can help you with, see :doc:`/integration/index`.

Quick Start

First, create an environment instance:

from webassets import Environment
my_env = Environment(
    directory='../static/media',
    url='/media')

As you can see, the environment requires two arguments:

• the path in which your media files are located
• the url prefix under which the media directory is available. This prefix will be used when generating output urls.

Next, you need to define your assets, in the form of so called bundles, and register them with the environment. The easiest way to do it is directly in code:

from webassets import Bundle
js = Bundle('common/jquery.js', 'site/base.js', 'site/widgets.js',
            filters='jsmin', output='gen/packed.js')
my_env.register('js_all', js)

However, 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 :doc:`helper classes <../loaders>` for some popular formats like YAML.

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. How you do this depends a bit on how your site is rendered.

>>> my_env['js_all'].urls()
('/media/gen/packed.js?9ae572c',)

This will always work. You can call your bundle's urls() method, which will automatically merge and compress the source files, and return the url to the final output file. Or, in debug mode, it would return the urls of each source file:

>>> my_env.debug = True
>>> my_env['js_all'].urls()
('/media/common/jquery.js',
 '/media/site/base.js',
 '/media/site/widgets.js',)

Take these urls, pass them to your templates, or otherwise ensure they'll be used on your website when linking to your Javascript and CSS files.

For some templating languages, webassets provides extensions to access your bundles directly within the template. See :doc:`../integration/index` for more information.

Using the Command Line Interface

See :doc:`/script`.

Further Reading

.. toctree::
    :maxdepth: 1

    /environment
    /bundles
    /script
    /builtin_filters
    /custom_filters
    /css_compilers
    /loaders
    /integration/index
    custom_resolver
    /faq