Theme SCSS Compiler

FAQ

Which SCSS version does this support?

The plugin bundles scssphp 2.1, which supports modern SCSS syntax compatible with Dart Sass.

When does a version actually get bumped?

Only when the compiled CSS output for that specific pair has changed compared to the previously written file. Comments-only edits or no-op SCSS changes that result in identical compressed CSS do not bust the cache. Other pairs keep their existing versions.

How does the per-pair Context (Frontend / Admin) setting work?

Each pair has a Context field. Pairs set to Frontend are auto-enqueued via wp_enqueue_scripts (only on the public site). Pairs set to Admin are auto-enqueued via admin_enqueue_scripts (only on /wp-admin pages). The style_loader_src version filter applies in both contexts whenever a configured CSS file is printed. Default for new pairs is Frontend.

Who can access the admin page?

By default only WordPress administrators (users with the manage_options capability). The Tools → Theme SCSS Compiler submenu, the form save handler, the AJAX compile endpoint and the auto-compile hook all enforce this capability. Editors, Authors and other roles cannot see or use the plugin’s UI.

If you need to grant access to a different role (for example a custom “Theme Developer” role), use the tscsscompiler_capability filter:

add_filter( 'tscsscompiler_capability', static function () {
    return 'edit_theme_options';
} );

What happens if the CSS file is missing?

If Auto-compile is enabled (default: on), every admin page load checks whether the configured CSS files exist or whether the SCSS source — or any of its @import-ed partials — is newer. Missing or stale outputs are compiled silently. This protects against white layouts after a fresh deployment or git pull.

Does it detect changes in `@import`-ed partials?

Yes. After every successful compile the plugin records the full list of files that scssphp pulled in (including transitive @import / @use / @forward chains) into a per-pair dependency map. The auto-compile check compares the modification time of each tracked partial against the CSS output. So if style.scss does @import "menu-styles"; and you edit menu-styles.scss, the next admin page load triggers a recompile automatically — you don’t have to touch style.scss.

Should I let the plugin enqueue my CSS, or do it in `functions.php`?

Both work. Auto-enqueue is on by default — the plugin runs wp_enqueue_style() for every configured pair on its respective context (Frontend or Admin). It runs at PHP_INT_MAX priority and skips any URL that’s already registered, so it never duplicates output. If you’d rather keep full control of the asset pipeline in your theme, just disable the option and call wp_enqueue_style() yourself.

Can I configure the plugin from code instead of the admin form?

Yes. Define TSCSSCOMPILER_PAIRS and the plugin reads pairs from there instead of the database. The admin form switches to a read-only state and the save handler is disabled.

define( 'TSCSSCOMPILER_PAIRS', [
    [ 'scss_path' => 'assets/scss/style.scss',       'css_path' => 'assets/css/style.css',       'version' => '1.0.0', 'context' => 'frontend' ],
    [ 'scss_path' => 'assets/scss/style-admin.scss', 'css_path' => 'assets/css/style-admin.css', 'version' => '1.0.0', 'context' => 'admin'    ],
] );

The remaining behaviours can be toggled individually:

• TSCSSCOMPILER_AUTO_COMPILE – true / false
• TSCSSCOMPILER_BUMP_VERSION – true / false (note: bumping is a no-op when defined via constant — versions live in your code)
• TSCSSCOMPILER_AUTO_ENQUEUE – true / false
• TSCSSCOMPILER_OUTPUT_STYLE – 'compressed' / 'expanded'

Where can I put the `define()` calls?

Three common places:

1. wp-config.php (loaded earliest, recommended for everything):

define( 'TSCSSCOMPILER_OUTPUT_STYLE', 'compressed' );

2. Theme functions.php (use the after_setup_theme hook so the constant exists by the time the plugin reads it):

add_action( 'after_setup_theme', static function () {
    if ( ! defined( 'TSCSSCOMPILER_PAIRS' ) ) {
        define( 'TSCSSCOMPILER_PAIRS', [
            [ 'scss_path' => 'assets/scss/style.scss', 'css_path' => 'assets/css/style.css', 'version' => '1.0.0', 'context' => 'frontend' ],
        ] );
    }
} );

3. .env + wp-config.php (Bedrock-style):

.env

TSCSSCOMPILER_AUTO_ENQUEUE=true
TSCSSCOMPILER_OUTPUT_STYLE=compressed

wp-config.php (or config/application.php in Bedrock)

if ( getenv( ‘TSCSSCOMPILER_AUTO_ENQUEUE’ ) !== false ) {
define( ‘TSCSSCOMPILER_AUTO_ENQUEUE’, filter_var( getenv( ‘TSCSSCOMPILER_AUTO_ENQUEUE’ ), FILTER_VALIDATE_BOOLEAN ) );
}
if ( $style = getenv( ‘TSCSSCOMPILER_OUTPUT_STYLE’ ) ) {
define( ‘TSCSSCOMPILER_OUTPUT_STYLE’, $style );
}

Pairs as a deep array don’t fit naturally in .env — define them in wp-config.php (or config/application.php in Bedrock) instead.

Why do I see a notice “Configured via wp-config.php” on the admin page?

That means TSCSSCOMPILER_PAIRS is defined somewhere (wp-config, theme, .env bridge). The form is intentionally read-only in that state — to make changes, edit the source where the constant is defined. Boolean toggles like …_AUTO_COMPILE defined via constants are also reflected as locked switches.

Is the plugin accessible?

Yes. The admin UI is built to WCAG 2.1 AA: semantic HTML with proper heading hierarchy, ARIA roles for status / alert regions, keyboard-focusable controls with visible focus rings, sufficient colour contrast (4.5:1 minimum for body text, 3:1 for UI components), and minimum 12px font size for caps-styled labels. All decorative SVG icons are marked aria-hidden="true".

Is there a German translation?

Yes, ships out of the box. All admin strings, hints and error messages are translated to German (de_DE).