Package: django-smartstaticfiles
django-smartstaticfilesenhances the functionalities ofcollectstaticmanagement command of Django1.11.x, allows for finer-grained control
over serving static files in production.Under the hood, it provides a file storage backend for use withSTATICFILES_STORAGEsetting, which inherits and improves Django’sManifestStaticFilesStoragestorage backend.FeaturesDeletes unhashed files and intermediate files by default.Optionally ignores hashing of specific files.Optionally minifies JavaScript and CSS files.Optionally replace JavaScript asset URLs with hashed versions usingloud commentsmarkup.(New in v0.2.0)Optimizes hashing process with fewer I/O and less calculation.Quick StartInstall the stable version from PyPI:pipinstalldjango-smartstaticfilesOr install the stable version with extras for JavaScript and CSS minification
(will also installrjsminandrcssmin):pipinstalldjango-smartstaticfiles[jsmin,cssmin]Or install the latest version from GitHub:pipinstallgit+https://github.com/rockallite/django-smartstaticfiles.gitAdd the following lines to the project’s Django settings module:STATIC_ROOT='/path/for/collecting/static/files'STATICFILES_STORAGE='django_smartstaticfiles.storage.SmartManifestStaticFilesStorage'# Remove this if you don't need to minify JavaScript and CSSSMARTSTATICFILES_CONFIG={'JS_MIN_ENABLED':True,'CSS_MIN_ENABLED':True,}In the project directory, collect static files by running the following
command:pythonmanage.pycollectstatic--clear--no-inputJavaScript Asset URLs Replacement(New in v0.2.0)By default, URLs of referenced assets (images, fonts, etc) in CSS
files will be replaced with hashed versions during processing.django-smartstaticfilesextends this feature to JavaScript files by
utilizing specialloud comments(/*! ... */) markup.Simple use caseThe JavaScript asset URLs replacement feature is disabled by default. To enable
it, add the following setting to Django settings module:SMARTSTATICFILES_CONFIG={# Enable JavaScript asset URLs replacement'JS_ASSETS_REPL_ENABLED':True,}To replace an asset URL with the hashed version, surround the URL string with/*! rev */and/*! endrev */markup:varimageURL=/*! rev */'../img/welcome.jpg'/*! endrev */;Supposed that the hashed filename iswelcome.ac99c750806a.jpg, the
processing result will be:varimageURL='../img/welcome.ac99c750806a.jpg';Only a single- or double-quoted bare string should be put inside/*! rev */and/*! endrev */markup. No comma or semicolon is allowed. Spaces around
or inside loud comments are optional, though.Using a different parent pathBy default, relative asset URLs are considered to be relative to the
referencing JavaScript file, just the same rule for a CSS file. However,
since JavaScript runs in global scope of a browser, the path of a
JavaScript file is sometimes not useful for locating relative assets.Therefore, the markup accepts a parameter asvirtual parent path, passing in
between a pair of parentheses right behind the loud comment starting tag, like
this:/*! rev(path) */. During processing, it will be considered as if it
were the parent path of the asset. For example:/*
 * Supposed there are following files:
 *     STATIC_URL/helloworld/img/welcome.jpg
 *     STATIC_URL/helloworld/js/main.js
 *
 * Then in the main.js:
 */varimageURLs=[// *** Absolute reference ***// (STATIC_URL as the root path)// Leading and trailing slashes in a virtual parent path are optional/*! rev(helloworld/img) */'welcome.jpg'/*! endrev */,/*! rev(/helloworld/img/) */'welcome.jpg'/*! endrev */,/*! rev(/helloworld/img) */'welcome.jpg'/*! endrev */,/*! rev(helloworld/img/) */'welcome.jpg'/*! endrev */,// A leading dot slash (./) or dot-dot slash (../) in an asset URL is OK/*! rev(helloworld/img) */'./welcome.jpg'/*! endrev */,/*! rev(helloworld/img) */'../img/welcome.jpg'/*! endrev */,// Use different path portion in a virtual parent path. A single slash means root (STATIC_URL)./*! rev(helloworld) */'img/welcome.jpg'/*! endrev */,/*! rev(/) */'helloworld/img/welcome.jpg'/*! endrev */,// *** Relative reference ***// (Relative to the JavaScript file)// A leading dot (.) or dot-dot (..) path part in a virtual parent path indicates a relative reference/*! rev(../img) */'welcome.jpg'/*! endrev */,/*! rev(..) */'img/welcome.jpg'/*! endrev */,/*! rev(../..) */'helloworld/img/welcome.jpg'/*! endrev */];After processing, the above code becomes:/*
 * Supposed there are following files:
 *     STATIC_URL/helloworld/img/welcome.jpg
 *     STATIC_URL/helloworld/js/main.js
 *
 * Then in the main.js:
 */varimageURLs=[// *** Absolute reference ***// (STATIC_URL as the root path)// Leading and trailing slashes in a virtual parent path are optional'welcome.ac99c750806a.jpg','welcome.ac99c750806a.jpg','welcome.ac99c750806a.jpg','welcome.ac99c750806a.jpg',// A leading dot slash (./) or dot-dot slash (../) in an asset URL is OK'./welcome.ac99c750806a.jpg','../img/welcome.ac99c750806a.jpg',// Use different path portion in a virtual parent path. A single slash means root (STATIC_URL).'img/welcome.ac99c750806a.jpg','helloworld/img/welcome.ac99c750806a.jpg',// *** Relative reference ***// (Relative to the JavaScript file)// A leading dot (.) or dot-dot (..) path part in a virtual parent path indicates a relative reference'welcome.ac99c750806a.jpg','img/welcome.ac99c750806a.jpg','helloworld/img/welcome.ac99c750806a.jpg'];Notice thatSTATIC_URLWILL NOT be prepended to the final URL. You
have to pass the value ofSTATIC_URLto the browser, e.g. via Django
templates in dynamic generated JavaScript code, and then manually concatenate the value and the URL path in JavaScript.Customizing the tag nameYou can also use a custom tag name in loud comments markup via the following
setting in Django settings module:SMARTSTATICFILES_CONFIG={# ...# Tag name of loud comments used in JavaScript asset URLs replacement'JS_ASSETS_REPL_TAG':'hash-it',}Then the corresponding JavaScript code should be written as:varimageURL=/*! hash-it */'../img/welcome.jpg'/*! endhash-it */;Hints about minificationIf you use a customized JavaScript minification function, you should ensure
that loud comments (/*! ... */) are preserved after processing.
Otherwise, JavaScript asset URLs replacement won’t work. The defaultjsminlibrary takes care of that.Some JavaScript minification libraries (e.g.jsmin) will deliberately
insert a newline at the end of each loud comment after minification. For
example, supposed that there is following code:varimageURL=/*! rev */'../img/welcome.jpg'/*! endrev */;varmehFace='mehFace';It would be minified as:varimageURL=/*! rev */'../img/welcome.jpg'/*! endrev */;varmehFace='mehFace';This is totally acceptable in most cases. However, it is still possible that
it causes unexpected results insome edge casesor drives perfectionists
nuts. You can telldjango-smartstaticfilesto remove one trailing newline
(if presents) from each replaced URL in JavaScript by setting"JS_ASSETS_REPL_TRAILING_FIX"toTrue. The final result after URLs
replacement would be:varimageURL='../img/welcome.ac99c750806a.jpg';varmehFace='mehFace';(New in v0.3.0: theJS_ASSETS_REPL_TRAILING_FIXsetting was added and defaults toTrue.)(New in v0.3.1: theJS_ASSETS_REPL_TRAILING_FIXsetting was set toFalseby default.)ConfigurationsAll configurations ofdjango-smartstaticfilesare in theSMARTSTATICFILES_CONFIGproperty of
Django settings module, a dict containing configuration keys. All
keys are optional, which means you don’t even need aSMARTSTATICFILES_CONFIGproperty at all if the default values meet your needs.Possible keys and default values are listed below:SMARTSTATICFILES_CONFIG={# Whether to enable JavaScript minification.'JS_MIN_ENABLED':False,# Whether to enable CSS minification.'CSS_MIN_ENABLED':False,# File patterns for matching JavaScript assets (in relative URL without# STATIC_URL prefix)'JS_FILE_PATTERNS':['*.js'],# File patterns for matching CSS assets (in relative URL without# STATIC_URL prefix)'CSS_FILE_PATTERNS':['*.css'],# Dotted string of the module path and the callable for JavaScript# minification. The callable should accept a single argument of a string# of the content of original JavaScript, and return a string of minified# content. (Notice that loud comments such as /*! ... */ must be preserved# in the result so as to make JavaScript asset URLs replacement work.)# The result will be cached and reused when possible.'JS_MIN_FUNC':'rjsmin.jsmin',# Extra keyword arguments which are sent to the callable for JavaScript# minification. They are sent after the argument of a string of the# content of original JavaScript. If no keyword arguments are sent, set it# to an empty dict ({}) or None.'JS_MIN_FUNC_KWARGS':{'keep_bang_comments':True,},# Dotted string of the module path and the callable for CSS# minification. The callable should accept a single argument of# string which contains the content of original CSS, and return a# string of minified content. The result will be cached and# reused when possible.'CSS_MIN_FUNC':'rcssmin.cssmin',# Extra keyword arguments which are sent to the callable for CSS# minification. They are sent after the argument of a string of the# content of original CSS. If no keyword arguments are sent, set it# to an empty dict ({}) or None.'CSS_MIN_FUNC_KWARGS':{'keep_bang_comments':True,},# A regular expression (case-sensitive by default) which is used to# search against assets (in relative URL without STATIC_URL prefix). The# mathced assets won't be minified. Set it to None to ignore no assets.# (Assets with .min.js or .min.css extensions are always ignored.)'RE_IGNORE_MIN':None,# Whether to enable deletion of unhashed files.'DELETE_UNHASHED_ENABLED':True,# Whether to enable deletion of intermediate hashed files.'DELETE_INTERMEDIATE_ENABLED':True,# A regular expression (case-sensitive by default) which is used to# search against assets (in relative URL without STATIC_URL prefix). The# matched assets won't be hashed. Set it to None to ignore no assets.'RE_IGNORE_HASHING':None,# Whether to enable JavaScript asset URLs replacement.'JS_ASSETS_REPL_ENABLED':False,# Tag name of loud comments used in JavaScript asset URLs replacement.'JS_ASSETS_REPL_TAG':'rev',# Whether to remove one trailing newline (if presents) after each# replaced URL in JavaScript. This is effective only if "JS_MIN_ENABLED"# is set to True. This fixes the problems and annoyances caused by a# deliberately added newline at the end of each loud comment by certain# minification libraries (e.g. jsmin).'JS_ASSETS_REPL_TRAILING_FIX':False,}ExtensibilityTheSmartManifestStaticFilesStoragestorage backend provided bydjango-smartstaticfilesinherits two parent
classes:classSmartManifestStaticFilesStorage(SmartManifestFilesMixin,StaticFilesStorage):passThe main logic is implemented inSmartManifestFilesMixin,
which is similar to Django’sManifestStaticFilesStorage:classManifestStaticFilesStorage(ManifestFilesMixin,StaticFilesStorage):passThe goal of this project is to makeSmartManifestFilesMixina drop-in replacement forManifestFilesMixin, without sacrificing
functionalities or performance. So you can combineSmartManifestFilesMixinwith other storage class that is compatible withManifestFilesMixin.For example,django-s3-storageprovides a storage backend which utilizes
Django’sManifestFilesMixin:# django_s3_storage/storage.pyfromdjango.contrib.staticfiles.storageimportManifestFilesMixin# ...classManifestStaticS3Storage(ManifestFilesMixin,StaticS3Storage):passYou can make a similar but enhanced storage backend by replacing it withSmartManifestFilesMixin:fromdjango_s3_storage.storageimportStaticS3Storagefromdjango_smartstaticfiles.storageimportSmartManifestFilesMixinclassSmartManifestStaticS3Storage(SmartManifestFilesMixin,StaticS3Storage):passWhy Django 1.11.x only?Until version 1.11, Django shipped with aManifestStaticFilesStoragestorage
backend that hada broken implementation. In other words, content changes in
referenced files (images, fonts, etc) aren’t represented in hashes of
referencing files (CSS files, specifically). This breaks the foundation of
cache-busting mechanism.Then, there are significant code changes in Django 1.11.x in order to fix the
behavior of theManifestStaticFilesStoragestorage backend. And it becomes
impractical to maintain compatibility ofdjango-smartstaticfileswith older
Django code. Therefore, only Django 1.11.x is supported (the latest version at
the time of writing).