Theme SCSS Compiler

No. The compiler is PHP and ships with the plugin. Nothing is installed on the server, nothing runs on your machine. You need WordPress 6.3 and PHP 8.1 or newer.

Everything you reach for in a theme stylesheet: nesting, the & parent selector, variables, mixins, functions, @extend , @media nesting, arithmetic, interpolation, and @import for splitting your styles into partials. Import chains nest as deep as you like, and every file in the chain is tracked for change detection.

Partials are the @import kind, so _variables.scss is pulled in with @import "variables"; at the top of your entry file, and everything it declares is available below. The compiler is a PHP port of Sass rather than Dart Sass, so it is worth a look at the compiled output the first time you move an existing theme over.

Give a partial a leading underscore and pull it in with @import at the top of your entry file. Everything a partial declares is available to everything below it.

// assets/scss/_variables.scss $brand: #0073aa; $text: #1f232b; $radius: 8px; // assets/scss/_card.scss .card { color: $text; border-radius: $radius; } // assets/scss/_menu.scss .menu a { color: $brand; } // assets/scss/style.scss — the file you set as the pair's SCSS source @import "variables"; @import "card"; @import "menu";

Note the import name drops both the underscore and the extension: the file _card.scss is imported as "card" .

Two things follow from this, and both are easier to get right if you know them up front.

Order matters. A partial is read at the position where you import it, so @import "variables" has to come before the partials that use those variables. Variables first, the rest below.

One shared scope. Every partial writes into the same namespace, so two partials that each declare $padding will quietly disagree — last one wins. Prefix instead: $card-padding , $menu-padding . Same for mixin names.

When the list gets long, collect it in one index partial and import just that:

// assets/scss/_index.scss @import "variables"; @import "card"; @import "menu"; // assets/scss/style.scss @import "index";

Chains nest as deep as you like. The plugin records every file that was read at any depth, so editing _card.scss two levels down still triggers the rebuild on your next admin page load.

Every valid CSS file is already valid SCSS, so you can rename style.css to style.scss and start there.

Nesting. Write child selectors inside the parent instead of repeating it:

.card { padding: 1rem; a { color: rebeccapurple; } }

compiles to .card { padding: 1rem; } and .card a { color: rebeccapurple; } .

The & parent reference, useful for states:

.button { background: #0073aa; &:hover { background: #005177; } &.active { background: #003f66; } }

compiles to .button , .button:hover and .button.active with those three colours.

Variables. Set a value once and reuse it:

$brand: #0073aa; a { color: $brand; } .button { background: $brand; }

One thing that surprises people: the default output style is compressed, so the compiled file is one long line and rebeccapurple has become #639 . Set the compiler to Expanded while you are learning. Full language guide: https://sass-lang.com/guide/

Yes, one kind of file. It is a compiler, so the boundary matters more than a reassuring “no”.

It writes the CSS target of each pair, for example assets/css/style.css . That file is replaced in full on every compile, so treat it as build output and never hand-edit it. It also creates the directory for that file when the directory does not exist.

Each compile briefly writes a second file next to the target, style.css.tscsscompiler-tmp , and renames it onto the target when it is finished — that is what makes the swap atomic. It is gone by the time the compile returns. The name deliberately does not end in .css , so if a process is killed part-way the leftover is never served as a stylesheet; you can delete it.

It writes nothing else. Your SCSS is only read. functions.php , templates and every other non- .css file are unreachable, because a target without a .css extension is refused before the write. Nothing outside the active theme can be written either: .. is rejected, and a target that turns out to be a symlink pointing out of the theme is rejected too.

Cache-busting versions are never written into a file. They go onto the stylesheet URL at request time through the style_loader_src filter, so your theme’s own wp_enqueue_style() calls stay as they are.

One thing to watch: the target does not have to be a new file. Point a pair at a .css file that already exists in your theme and that file is replaced.

No, that one target is refused. style.css is where WordPress reads Theme Name: from, and a compile replaces the whole file, so one typo there would leave the theme unrecognisable and drop it out of Appearance → Themes . The plugin says so instead of writing.

Compile to a separate file and enqueue it alongside your style.css :

assets/scss/style.scss → assets/css/style.css

Any other name works too. Only the theme’s own root style.css is off limits; a style.css in a subfolder is fine.

Only when that pair’s freshly compiled CSS differs from the file already on disk. Other pairs keep their version.

An edit that produces identical CSS does not move the version. That covers // comments in any mode, and /* */ comments in compressed output, because those are stripped. In expanded output a /* */ comment is part of the CSS, so editing one is a real change and does bump the version.

Versions are three-part numbers and the patch digit advances: 1.0.4 becomes 1.0.5 .

Two separate settings, with different defaults.

Auto-compile is on by default. On every wp-admin page load it checks whether any compiled CSS is missing or older than its SCSS source or tracked partials, and rebuilds what needs it. Nothing runs on a schedule; your own page load triggers it.

Auto-recompile is off by default. Turn it on and the settings page runs a countdown, from 1 to 999 seconds, and re-checks on each tick while that page stays open in your browser. It counts down only while that tab is the one you are looking at, and it holds off while the form has unsaved changes; the readout says which of the two is happening. It compiles only when something actually changed, so a page left open does not keep rewriting the CSS.

They are independent. Switching Auto-compile off does not stop the timer. To compile only on the button, switch both off.

In this order:

1. 01Did you save the settings? Compile now is locked while the form has unsaved changes, and clicking it then does nothing.
2. 02Press Compile now and read the message. A missing source file or a syntax error shows up here.
3. 03Look at the pair’s version. If it did not move, the compiled CSS came out identical and the browser is correctly serving what it has.
4. 04Check whether “Bump CSS version after each compile” is on. With it off the URL never changes and browser caches keep the old file.
5. 05If pairs come from TSCSSCOMPILER_PAIRS , versions are never rewritten. Edit the version value in your code.
6. 06Check your caching plugin and CDN. A version in the URL does not help if something upstream serves a cached response.

Each target is written inside the active theme at the path you configured. With Auto-compile on, the next wp-admin page load notices a missing file and builds it, so a deploy or a git pull without compiled CSS does not leave the site unstyled. Nothing rebuilds until someone with access opens an admin page, though, and the pair is not enqueued in the meantime. Deploying to production without visiting wp-admin means you should commit the compiled CSS.

Yes. After each successful compile the plugin stores every file the compiler read, including nested import chains, and Auto-compile compares each of them against the compiled CSS. So if style.scss does @import "menu"; and you only edit _menu.scss , the next admin page load recompiles. You never have to touch the entry file.

No. Compiling happens only in wp-admin, for a logged-in user who passes the capability check, and it is triggered in exactly three places: an admin page load with Auto-compile on, the Compile now button, and the settings-page timer. The last two are admin-ajax requests, so also wp-admin. There is no WP-Cron job and no scheduled task. Visitors are served the already compiled file and never cause any Sass work.

On Tools → Theme SCSS Compiler . A failed compile is kept in a “Last compile error” panel with server paths stripped from the message, and a successful compile clears it. The stored error also expires by itself after 24 hours. Compile now reports success or failure right away. There is no notice on other admin screens, so a failed auto-compile is visible only on the plugin’s own page.

Each pair has one. Frontend pairs are enqueued on wp_enqueue_scripts , so on the public site only. Admin pairs are enqueued on admin_enqueue_scripts , so in wp-admin only. The version filter applies in both. New pairs start as Frontend.

Yes, and the active child theme is the boundary. Paths resolve against the active stylesheet directory, which is the child when one is active. That is also the limit: a path containing .. is refused, and while an @import can read a file in the parent theme, the compile is stopped before anything is written. If the SCSS you want to compile lives in the parent theme, confi