Theme SCSS Compiler

Your theme has a .scss file. Your site needs a .css file. Theme SCSS Compiler does that one conversion, on your server, from Tools → Theme SCSS Compiler.

You give it a source and a target, for example assets/scss/style.scss and assets/css/style.css. Save the SCSS, open any admin page, and the CSS is rebuilt. No Node.js, no npm install, no Gulp task, no CI step: the Sass compiler (scssphp) ships inside the plugin. SCSS is the Sass syntax that looks like CSS. Every valid CSS file is already valid SCSS, and you get nesting, variables, mixins and @import on top.

It is built for the case that keeps coming up: a theme with one or two stylesheets, hosting where a build pipeline is not going to happen, and someone who wants to change a variable and see the result.

Features

• As many SCSS to CSS pairs as the theme needs. Both paths are relative to the active theme.
• A Frontend or Admin context per pair, enqueued on the matching hook.
• A cache-busting version per pair, applied to the stylesheet URL through the style_loader_src filter.
• Versions move only when that pair’s compiled CSS really came out different.
• Import tracking. Edit a partial and the next admin page load rebuilds.
• Compressed output for production, expanded when you need to read it.
• Auto-compile on missing or stale CSS, so a deploy does not leave the site unstyled.
• An optional recompile timer on the settings page. Off by default.
• Auto-enqueue that steps aside when a stylesheet URL is already registered.
• A Theme CSS status table listing the stylesheets it finds in the active theme.
• Compile button with live feedback and a persistent error panel.
• Compiled CSS is swapped into place atomically, so a visitor is never served a half-written stylesheet.
• A compile lock, so two administrators pressing Compile at the same moment do not build the same CSS twice.
• Configuration from PHP constants instead of the database, for wp-config.php, a theme, or Bedrock.
• Administrators only by default, with a capability filter.
• PHP 8.1+, accessible admin UI, German translation included.

Scope

The whole plugin works inside one theme, the active one. Both paths of a pair resolve against it, and that is also the write boundary: a path containing .. is refused, and nothing is ever written outside the theme. An @import inside your SCSS can still read a file elsewhere on the server, and output built from one is refused before it reaches disk. With a child theme active, the child is that theme.

That keeps the tool small on purpose. One theme, its stylesheets, nothing else to configure.

Where the compiled CSS goes

Compiling writes into your theme. It writes the CSS target of each pair, plus a short-lived temporary file beside it that is renamed onto the target when the compile finishes, and it creates the directory for the target if it is missing. Nothing else in the theme is touched: sources are only read, and a target that is not a .css file is refused before the write, so a mistyped path cannot land on functions.php.

Commit those CSS files or add them to .gitignore. Both work, because auto-compile rebuilds anything missing.

Privacy

No external HTTP requests, no cookies, no telemetry, no tracking. Everything happens on your server. The plugin bundles scssphp and its dependencies (league/uri, scssphp/source-span, symfony/filesystem, the symfony ctype and mbstring polyfills, and the PSR HTTP interfaces). All are MIT licensed and GPL-compatible, and their source sits in the plugin’s vendor/ directory.