django-libsass

0.9 · active · verified Sun Apr 12

django-libsass is a Django Compressor filter that compiles Sass (SCSS) files using the `libsass-python` binding of LibSass. It integrates seamlessly into Django's static files and compressor pipeline, allowing developers to write Sass without external build tools. The current version is 0.9, and it receives infrequent but active maintenance updates for Django compatibility.

Warnings

deprecated The underlying LibSass library is officially deprecated by the Sass team in favor of Dart Sass. While `libsass-python` and `django-libsass` will continue to receive maintenance updates, no new features or compatibility with future Sass language updates are planned. Consider this for long-term project planning.
Fix: Be aware of potential future limitations. For new projects, evaluate alternatives like `django-sass-processor` with Dart Sass if cutting-edge Sass features are required.
breaking Older versions of `django-libsass` may not be compatible with newer Django or `django-compressor` versions. For example, v0.6 fixed compatibility with `django-compressor` 1.6, and v0.9 added support for Django 3.1/3.2.
Fix: Always use the latest stable version of `django-libsass` to ensure compatibility with your Django and `django-compressor` versions. Check release notes for specific version requirements.
gotcha When using CSS frameworks like Bootstrap that rely on high precision in Sass calculations, the default `LIBSASS_PRECISION` (5) might be insufficient, leading to layout issues. Bootstrap, for instance, typically requires a precision of 8.
Fix: Set `LIBSASS_PRECISION = 8` (or higher if needed) in your `settings.py` when using such frameworks.
gotcha While `django-libsass` attempts to resolve `@import` paths using `STATICFILES_FINDERS`, explicitly traversing up the directory tree with `../` in `@import` statements might not work reliably and is discouraged by some related tools.
Fix: Organize your SCSS files so that `@import` paths are relative to a recognized static files directory or an entry in `LIBSASS_ADDITIONAL_INCLUDE_PATHS`. Avoid `../` in `@import` statements.
gotcha Installing multiple Python packages that provide a `sass` module (e.g., `libsass` and other Sass processors) can lead to namespace conflicts and errors like `module 'object' has no attribute 'compile'`.
Fix: Ensure only `libsass` (via `pip install libsass`) is installed as your Sass compiler if you are using `django-libsass`. Uninstall other conflicting Sass-related Python packages.

Install

pip install django-libsass django-compressor libsass Install with dependencies

Imports

SassCompiler
```
from django_libsass import SassCompiler
```
Used to configure django-compressor to use SassCompiler as a precompiler for 'text/x-scss' content types.

Quickstart

To quickly integrate `django-libsass`, first ensure `django-compressor` is set up. Add `compressor` to `INSTALLED_APPS` and `compressor.finders.CompressorFinder` to `STATICFILES_FINDERS`. Then, configure `COMPRESS_PRECOMPILERS` in your `settings.py` to use `django_libsass.SassCompiler` for `text/x-scss` files. Finally, in your Django templates, load the `compress` and `static` tags and wrap your SCSS `link` tag within `{% compress css %}` and `{% endcompress %}` blocks, specifying `type="text/x-scss"`.

import os

# settings.py

INSTALLED_APPS = [
    # ...
    'compressor',
    'django.contrib.staticfiles',
    # 'your_app' (where your .scss files live in static/your_app/)
]

STATIC_URL = '/static/'
STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'compressor.finders.CompressorFinder',
)

COMPRESS_PRECOMPILERS = (
    ('text/x-scss', 'django_libsass.SassCompiler'),
)

COMPRESS_ENABLED = True # Set to False in production for offline compression
COMPRESS_OFFLINE = False # Set to True in production for offline compression

# Optional: Configure additional libsass settings
# LIBSASS_OUTPUT_STYLE = 'compressed'
# LIBSASS_PRECISION = 8 # Recommended for frameworks like Bootstrap
# LIBSASS_ADDITIONAL_INCLUDE_PATHS = [
#     os.path.join(BASE_DIR, 'path/to/extra/sass/includes'),
# ]

# templates/base.html
# ...
# {% load static %}
# {% load compress %}
# ...
# {% compress css %}
#   <link rel="stylesheet" type="text/x-scss" href="{% static 'your_app/css/main.scss' %}">
# {% endcompress %}
# ...

# your_app/static/your_app/css/main.scss
// Example SCSS content
$primary-color: #337ab7;

body {
  background-color: lighten($primary-color, 40%);
  a {
    color: $primary-color;
    &:hover {
      text-decoration: underline;
    }
  }
}

view raw JSON →