Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tav/assetgen

Asset generator for modern web app development
https://github.com/tav/assetgen

Last synced: 3 months ago
JSON representation

Asset generator for modern web app development

Awesome Lists containing this project

README 

        
Assetgen is intended as a replacement for the various ad-hoc scripts that often

get written to build/manage JavaScript/CSS files.



**Features**



The default support includes:



* Compiling CoffeeScript/TypeScript source files into JavaScript.



* Minifying with UglifyJS/UglifyJS2 -- including constant folding support.



* Generating source maps for CoffeeScript, TypeScript and minified JavaScript

  sources.



* Compiling and minifying CSS from Less, Roole, SASS, SCSS and Stylus source

  files.



* Generating variants of the same stylesheet for internationalisation

  (flipping left to right).



* Embedding image/font resources as ``data:`` URIs within CSS stylesheets to

  minimise latency.



* Concatenating multiple source files into one file to minimise the number of

  HTTP requests.



* Creating distinct files with the hash of the content embedded in the filename

  so as to work effectively with web caches.



* Dynamically fetching source files and embedded resources from HTTP/HTTPS URLs.



* Creating a JSON manifest file for use in your web app's static handlers.



* Generating files processed by a templating language (e.g. for inserting content from other files).



The tool is driven by the configuration you specify in an ``assetgen.yaml``

file, e.g.



::



   # Example assetgen.yaml configuration



   generate:



   - js/base.js:

       source:

         - %(AMPIFY_ROOT)s/third_party/jslibs/json.js



   - js/app.js:

       source:

         - https://raw.github.com/tav/jsutil/master/define.coffee

         - static/js/models.coffee

         - static/js/views.coffee

       uglify.define:

         - DEBUG=false

       profile.dev:

         uglify.define:

           - DEBUG=true



   - js/encoder.js:

       source:

         - encoder/detect.ts

         - encoder/format.ts

         - encoder/encode.ts

       sourcemaps: true



   - js/content-inserter.js

        source:

          - static/html/content.html # plain html content

          - static/js/Content.coffee # content handling logic

          - raw: "})();"

        template: |

          (function(){var htmlContent = ${source|trim,jsliteral};

        # the source parameter gets processesed for each static source

        # file (i.e. not raw strings) which is not processed in any way

        # i.e. not CoffeeScript/TypeScript files.

        # Also, templates only works when source maps are disabled

        sourcemaps: false



   - gfx/*:

       source: static/gfx/*

       type: binary



   - css/site.css:

       source:

         - raw: |

             // Public Domain (-) 2013 The Ampify Authors.

             // See the Ampify UNLICENSE file for details.

         - static/css/site.sass

       depends:

         - static/css/*.sass

         - static/gfx/*

       bidi: true

       embed.path.root: static

       embed.url.base: /.static/



   prereqs:



   - static/js/consts.js:

       source: static/js/consts.coffee

       compress: false



   - static/js/consts-dev.js:

       source: static/js/consts-dev.coffee

       compress: false



   env:

     NODE_PATH.prefix: static/js



   output.directory: appengine/static

   output.hashed: true

   output.gzip: true

   output.manifest: appengine/assets.json



   profile.dev:

     css.compress: false

     js.compress: false



To take advantage of the embedding within stylesheets just replace ``url()``

entries with ``embed()`` entries in your source stylesheet files -- whether

that is less, sass, scss, stylus or plain old CSS.



You can control which config options gets used by specifying the ``--profile``

parameter. This will override default values with the values specified for the

given profile. So, in the above example, specifying ``--profile dev`` will use

all the ``profile.dev`` options.



And, whilst you are developing, you can use the ``--watch`` command-line

parameter to tell ``assetgen`` to monitor file changes and rebuild all

appropriate files. Watch also monitors changes to the ``assetgen.yaml`` file,

so you can update the config without having to restart ``assetgen``.



``output.hashed: true`` will put a unique file hash in the file name so that you

can set a long expiry date for HTTP caching on those files



``output.gzip: true`` will write an additional file with ``.gz`` on the end for

use with web servers that support sending a pre-compressed file, such as nginx's

``gzip_static`` module.



During development, one often runs ``--watch`` with a dev profile, e.g.



::



    assetgen --profile dev --watch



Then, to create the release/production builds, just remove the built files and

regenerate, i.e.



::



    assetgen --clean && assetgen



The above commands assume that you've commited an ``assetgen.yaml`` file into

a git repository. Assetgen will then use ``git`` to auto-detect the file from

within the current repository. If you are not using git or haven't committed

the config file, you can of course specify it explicitly, e.g.



::



    assetgen assetgen.yaml --profile dev --watch

    assetgen assetgen.yaml --clean && assetgen assetgen.yaml



If you are using ``bash``, you can take advantage of the tab-completion for

command line parameters support within ``assetgen`` by adding the following to

your ``~/.bashrc`` or equivalent::



    _assetgen_completion() {

        COMPREPLY=( $( \

        COMP_LINE=$COMP_LINE  COMP_POINT=$COMP_POINT \

        COMP_WORDS="${COMP_WORDS[*]}"  COMP_CWORD=$COMP_CWORD \

        OPTPARSE_AUTO_COMPLETE=1 $1 ) )

    }



    complete -o default -F _assetgen_completion assetgen



And, finally, you can specify custom handlers for ``assetgen`` to call when

generating a file of a given ``type``. For example, to override the builtin

``js`` handler with one which just lower-cases all the source content, create

your extension, e.g. ``kickass-extension.py``::



   class KickassAsset(Asset):



       def generate(self):

           content = ''.join(read(source).lower() for source in self.sources)

           self.emit(self.path, content)



   register_handler('js', KickassAsset)



Then run ``assetgen`` with the ``--extension path/to/kickass-extension.py``

parameter specified.



**Usage**



::



    Usage: assetgen [ ...] [options]



    Note:

        If you don't specify assetgen.yaml file paths, then `git

        ls-files *assetgen.yaml` will be used to detect all config

        files in the current repository. So you need to be inside

        a git repository's working tree.



        And if you specify a URL as a `source`, then it will be

        downloaded to ~/.assetgen -- you can override this by

        setting the env variable $ASSETGEN_DOWNLOADS



    Options:

      -h, --help        show this help message and exit

      -v, --version     show program's version number and exit

      --clean           remove all generated files

      --debug           set debug mode

      --extension=PATH  specify a python extension file (may be repeated)

      --force           force rebuild of all files

      --nuke            remove all generated and downloaded files

      --profile=NAME    specify a profile to use

      --watch           keep running assetgen on a loop



**Contribute**



To contribute any patches simply fork the repository using GitHub and send a

pull request to https://github.com/tav, thanks!



**License**



All of the code has been released into the `Public Domain

`_. Do with it as you

please.



-- 

Enjoy, tav