Django template tags to compile all kinds of static files (SASS, LESS, Stylus, CoffeeScript, Babel).
Project description
Django Static Precompiler
Django Static Precompiler provides template tags and filters to compile CoffeeScript, SASS / SCSS, LESS, Stylus, Babel and Handlebars. It works with both inline code and external files.
Installation
django-static-precompiler is avaiable through pip:
$ pip install django-static-precompiler
Add “static_precompiler” to INSTALLED_APPS setting.
Initialize DB:
On Django < 1.7 run syncdb or migrate static_precompiler if you use South (1.0 is required).
On Django >= 1.7 run migrate static_precompiler.
Make sure that you have necessary compilers installed.
Optionally, you can specify the full path to compilers (see below).
In case you use Django’s staticfiles contrib app you have to add static-precompiler’s file finder to the STATICFILES_FINDERS setting, for example:
STATICFILES_FINDERS = ( 'django.contrib.staticfiles.finders.FileSystemFinder', 'django.contrib.staticfiles.finders.AppDirectoriesFinder', # other finders.. 'static_precompiler.finders.StaticPrecompilerFinder', )
Note that by default compiled files are saved into COMPILED folder under your STATIC_ROOT (or MEDIA_ROOT if you have no STATIC_ROOT in your settings). You can change this folder with STATIC_PRECOMPILER_ROOT and STATIC_PRECOMPILER_OUTPUT_DIR settings.
Note that all relative URLs in your stylesheets are converted to absolute URLs using your STATIC_URL setting.
compile template filter
compile is a template filter that allows to compile any source file supported by compilers configured with STATIC_PRECOMPILER_COMPILERS settings.
Example Usage
{% load compile_static %} {% load static %} <script src="{% static "path/to/script.coffee"|compile %}"></script> <link rel="stylesheet" href="{% static "path/to/styles1.less"|compile %}" /> <link rel="stylesheet" href="{% static "path/to/styles2.scss"|compile %}" />
renders to:
<script src="/static/COMPILED/path/to/script.js"></script> <link rel="stylesheet" href="/static/COMPILED/path/to/styles1.css" /> <link rel="stylesheet" href="/static/COMPILED/path/to/styles2.css" />
{% inlinecompile %} tag
Compiles everything between {% inlinecompile %} and {% endinlinecompile %} with compiler specified by name. Compiler must be specified in STATIC_PRECOMPILER_COMPILERS setting. Names for default compilers are:
coffeescript
babel
less
sass
scss
stylus
Example Usage
{% load compile_static %} <script type="text/javascript"> {% inlinecompile "coffeescript" %} console.log "Hello, World!" {% endinlinecompile %} </script>
renders to:
<script type="text/javascript"> (function() { console.log("Hello, World!"); }).call(this); </script>
General settings
- STATIC_PRECOMPILER_COMPILERS
List of enabled compilers. You can modify it to enable your custom compilers. Default:
STATIC_PRECOMPILER_COMPILERS = ( 'static_precompiler.compilers.CoffeeScript', 'static_precompiler.compilers.Babel', 'static_precompiler.compilers.Handlebars', 'static_precompiler.compilers.SASS', 'static_precompiler.compilers.SCSS', 'static_precompiler.compilers.LESS', 'static_precompiler.compilers.Stylus', )
You can specify compiler options using the following format:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.CoffeeScript', {"executable": "/usr/bin/coffeescript"}), ('static_precompiler.compilers.SCSS', {"compass_enabled": True}), )
- STATIC_PRECOMPILER_ROOT
Controls the absolute file path that compiled files will be written to. Default: STATIC_ROOT.
- STATIC_PRECOMPILER_OUTPUT_DIR
Controls the directory inside STATIC_PRECOMPILER_ROOT that compiled files will be written to. Default: "COMPILED".
- STATIC_PRECOMPILER_USE_CACHE
Whether to use cache for inline compilation. Default: True.
- STATIC_PRECOMPILER_CACHE_TIMEOUT
Cache timeout for inline styles (in seconds). Default: 30 days.
- STATIC_PRECOMPILER_MTIME_DELAY
Cache timeout for reading the modification time of source files (in seconds). Default: 10 seconds.
- STATIC_PRECOMPILER_CACHE_NAME
Name of the cache to be used. If not specified then the default django cache is used. Default: None.
- STATIC_PRECOMPILER_PREPEND_STATIC_URL
Add STATIC_URL to the output of template tags and filters. Default: False
- STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE
Disable automatic compilation from template tags or compile_static utility function. Files are compiled only with compilestatic command (see below). Default:: False
- STATIC_PRECOMPILER_LIST_FILES
Whether or not static_precompiler.finders.StaticPrecompilerFinder will list compiled files when collectstatic command is executed. Set to True if you want compiled files to be found by collectstatic. Default:: False.
Compiler specific settings
CoffeeScript
- executable
Path to CoffeeScript compiler executable. Default: "coffee".
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.CoffeeScript', {"executable": "/usr/bin/coffee", "sourcemap_enabled": True}), )
Babel
- executable
Path to Babel compiler executable. Default: "babel".
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
- plugins
Babel plugins command line option. Default: None (uses Babel’s default option).
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.Babel', {"executable": "/usr/bin/babel", "sourcemap_enabled": True, "plugins": "transform-react-jsx"}), )
Handlebars
- executable
Path to Handlebars compiler executable. Default: "handlebars".
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
- known_helpers
List of known helpers (-k compiler option). Default: None.
- namespace
Template namespace (-n compiler option). Default: None.
- simple
Output template function only (-s compiler option). Default: False.
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.Handlebars', {"executable": "/usr/bin/handlebars", "sourcemap_enabled": True, "simple": True}), )
SASS / SCSS
- executable
Path to SASS compiler executable. Default: “sass”.
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
- compass_enabled
Boolean. Whether to use compass or not. Compass must be installed in your system. Run “sass –compass” and if no error is shown it means that compass is installed.
- load_paths
List of import paths (--load-path command line option).
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.SCSS', {"executable": "/usr/bin/sass", "sourcemap_enabled": True, "compass_enabled": True, "load_paths": ["path"]}), )
LESS
- executable
Path to LESS compiler executable. Default: "lessc".
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.LESS', {"executable": "/usr/bin/lessc", "sourcemap_enabled": True), )
Stylus
- executable
Path to Stylus compiler executable. Default: "stylus".
- sourcemap_enabled
Boolean. Set to True to enable source maps. Default: False
Example:
STATIC_PRECOMPILER_COMPILERS = ( ('static_precompiler.compilers.Stylus', {"executable": "/usr/bin/stylus", "sourcemap_enabled": True), )
Usage with forms media
If you want to use static_precompiler in form media definitions, you can use the following approach:
from django import forms from static_precompiler.utils import compile_static class MyForm(forms.Form): @property def media(self): return forms.Media( css={"all": ( compile_static("styles/myform.scss"), )}, js=( compile_static("scripts/myform.coffee"), ) )
compilestatic management command
Django Static Precompiler includes a management command compilestatic. It will scan your static files for source files and compile all of them.
You can use this command in conjunction with STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE setting if you use custom STATICFILES_STORAGE such as S3 or some CDN. In that case you can should run compilestatic every time when your source files change and then run collectstatic.
You can run compilestatic in watch mode (--watch option). In watch mode it will monitor the changes in your source files and re-compile them on the fly. It can be handy if you use tools such as LiveReload.
You should install Watchdog to use watch mode or install django-static-precompiler with the watch extra:
$ pip install django-static-precompiler[watch]
Troubleshooting
If you get [Errno 2] No such file or directory make sure that you have the required compiler installed. For all compilers you can specify the path to executable file using the executable option, see examples above.
If you run migrate and get ImportError: cannot import name migrations then most likely you use Django < 1.7 and South < 1.0. You should either upgrade to Django 1.7+ or use South 1.0.
Changes
1.1
Add source maps support for SASS/SCSS
Add source maps support for LESS
Add source maps support for CoffeeScript
Add source maps support for Stylus
Add source maps support for Babel
Add Handlebars compiler
Add support for Django 1.9
Add plugins parameter to Babel compiler
Add load_paths parameter to SASS/SCSS compilers
1.0.1
Add modules parameter to Babel compiler
Allow to install Watchdog with pip install django-static-precompiler[watch]
1.0
Add compile template filter
Deprecate {% compile %} template tag
The following compiler specific template tags are REMOVED:
{% coffeescript %}
{% inlinecoffeescript %}
{% sass %}
{% inlinesass %}
{% scss %}
{% inlinescss %}
{% less %}
{% inlineless %}
Add Stylus compiler
0.9
Compiler options are specified with STATIC_PRECOMPILER_COMPILERS setting.
The following settings are DEPRECATED:
COFFEESCRIPT_EXECUTABLE
SCSS_EXECUTABLE
SCSS_USE_COMPASS
LESS_EXECUTABLE
-C (--no-cache) flag is removed from SASS/SCSS compilers
Add STATIC_PRECOMPILER_LIST_FILES setting
Add Babel compiler
0.8
Add {% inlinecompile %} template tag
The following compiler specific template tags are DEPRECATED:
{% coffeescript %}
{% inlinecoffeescript %}
{% sass %}
{% inlinesass %}
{% scss %}
{% inlinescss %}
{% less %}
{% inlineless %}
Use Django 1.7 migrations
BUGFIX: fix sass imports from scss and vice versa
BUGFIX: make sure that compilestatic works if watchdog isn’t installed.
BUGFIX: fix compilation error when dependency file was removed or renamed
0.7
Add compilestatic management command (replaces static_precompiler_watch)
Add STATIC_PRECOMPILER_DISABLE_AUTO_COMPILE to settings
Add STATIC_PRECOMPILER_CACHE_NAME to settings
Bugfixes
0.6
Add STATIC_PRECOMPILER_PREPEND_STATIC_URL to settings
Add {% compile %} template tag
0.5.3
Update the parsing of @import statements. Fix the bug with URLs containing commas.
0.5.2
static_precompiler_watch: watch for changes in all directories handled by static finders, not only STATIC_ROOT
static_precompiler_watch: add --no-initial-scan option
0.5.1
Fix SCSS compilation error when importing Compass styles
0.5
Add Python 3 support
0.4
Add compile_static and compile_static_lazy utility functions.
0.3
Bug fixes
Add Windows compatibility
0.2
Reduce the max length of varchar fields in Dependency model to meet MySQL limitations
static_precompiler_watch: don’t fall with exception on compilation errors or if source file is not found
0.1
Initial release
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for django-static-precompiler-1.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 92cadfd41556db601f0c57e0bb6a30fec9c3d6782741eeb65911476830c887a0 |
|
MD5 | e3d5f15b1f7e6c7e657f3baef73ffdbf |
|
BLAKE2b-256 | a36555452d2051e68dd0983ff6426b5d8f3b1a64ce29279a9ec3e6af3bd2f9e7 |