Skip to content

Sass and SCSS Tooling

Work in progress

Sass/SCSS support is staged in the codebase but currently disabled. The service, command group, and execution plumbing are present but the registration and watcher hooks are commented out. See Enabling Sass Support for the steps to turn it on.

Overview

The dev_tool integrates Dart Sass as the stylesheet compiler for projects that use SCSS. Sass is used for compiling SCSS source stylesheets to CSS, both as a one-shot build and as a watcher that recompiles on change during development.

Prerequisites

Local Mode

If your project uses local development mode, sass runs on your host machine. You do not need to install it manually — the dev_tool installs sass automatically the first time a styles command or the watcher runs, via bun add --global sass (auto-provisioning bun first if needed), the same way it provisions bun and uv.

To install it yourself ahead of time instead:

bun add --global sass

After installation, verify sass is available:

sass --version

Containerized Mode

In containerized development mode all Sass commands run inside the app container via docker exec. sass is installed in the app image (alongside bun), so no extra setup is required — rebuild the image if it predates this change.

Configuration

Sass-specific settings are configured under the [tool.dev_tool.sass] section of your pyproject.toml:

[tool.dev_tool.sass]
source_directories = ["static/scss"]
output_directory = "static/css"
style = "expanded"
source_map = true
Field Description Default
source_directories Directories containing SCSS source files. Each is compiled to output_directory. ["static/scss"]
output_directory Directory where compiled CSS is written. "static/css"
style Output style for development builds (expanded or compressed). "expanded"
source_map Whether to emit source maps for development builds. true

Production builds always use the compressed style and omit source maps, regardless of the style and source_map settings.

Styles Tab in the dev_tool

When enabled, the Styles tab provides access to the following commands:

Command Description
Compile SCSS to CSS Compiles SCSS using the configured style and source_map settings.
Compile SCSS to CSS (production) Compiles SCSS with the compressed style and no source maps.
Watch SCSS for changes Starts a Sass watcher that recompiles on every change until interrupted.

Sass Watcher

When source directories exist, the dev_tool can start a Sass watcher alongside the Django development server. The watcher monitors your SCSS source files for changes and automatically recompiles the CSS.

In local mode, the watcher runs as a local process (sass --watch <source>:<output>). In containerized mode, it runs inside the app container (docker exec -i <project>-app sass --watch <source>:<output>).

Enabling Sass Support

Sass support ships disabled. To enable it, uncomment the staged wiring:

  1. dev_tool/container/service_registry.py — uncomment the SassService import, the _create_sass_service factory, and its register_factory call.

  2. dev_tool/container/command_registry.py — uncomment the SassCommandGroup import and its register call.

  3. dev_tool/main.py — uncomment the SassCommandGroup import and the container.resolve(SassCommandGroup) call.

  4. dev_tool/commands/home.py (optional, for the auto-start watcher) — add a sass: SassService parameter to HomeCommandGroup, uncomment the self.sass = sass assignment, and uncomment the watcher block in run_server.

  5. mkdocs.yml — uncomment the Sass and SCSS Tooling navigation entry.

  6. Add the [tool.dev_tool.sass] section to your project's pyproject.toml.

  7. Containerized mode needs no extra setup — sass ships in the app image (rebuild the image if it predates this change). Local mode auto-installs sass on the host on first use.