HTML & CSS

Compile SCSS for a WordPress Theme with Dart Sass

Build theme SCSS into CSS with Dart Sass, preserve the theme header, enqueue the generated asset, and verify source changes before deployment.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Compile SCSS during theme development

A WordPress theme can use SCSS as maintained source, but the browser needs compiled CSS. Run Dart Sass in the theme’s development or release process, then enqueue the generated stylesheet through WordPress. Merely renaming a .scss file to .css or uploading it to the theme does not resolve Sass variables, mixins or modules.

Start by checking whether the theme already has a build system. If it does, use that system’s existing entry files and dependency versions. A second compiler watching the same source can generate conflicting output. For a new custom theme setup, keep SCSS and generated CSS in separate directories within the theme project.

Create an entry file and a design-value partial

assets/
  scss/_tokens.scss
  scss/theme.scss
  css/theme.css

Put reusable values in assets/scss/_tokens.scss. This example’s spacing and border color are intentionally easy to verify in the compiled output. The partial is loaded by the entry; it is not a separate file to link from a WordPress page.

// assets/scss/_tokens.scss
$space: 12px;
$accent: #0f766e;

// assets/scss/theme.scss
@use "tokens";

.theme-note {
  padding: tokens.$space;
  border-inline-start: 4px solid tokens.$accent;
}

The module namespace makes the origin of each value visible. Refer to the Sass @use documentation when organizing more complex modules. An import or module error is a compiler-input problem; changing the browser’s stylesheet link will not fix an unresolved Sass module.

Add a project-owned compiler command

Install the official sass package as a pinned development dependency in the theme’s existing npm project, keeping its package file and lockfile. If no package file exists, initialize one first. The Sass installation guide documents the available implementations; these examples use Dart Sass 1.105.0 through npm.

{
  "scripts": {
    "css:build": "sass --no-error-css --no-source-map assets/scss/theme.scss assets/css/theme.css"
  }
}

Run npm run css:build from the theme project. Inspect assets/css/theme.css for padding 12px and the #0f766e border color. Change the partial to 16px and #7c3aed, rebuild, and confirm both values change. This checks the actual entry-to-partial relationship instead of merely confirming that a CSS file exists.

Enqueue the generated CSS

Integrate the generated path into the theme’s existing enqueue function. For a new custom asset, a registration can use the following pattern. Preserve actual dependency handles and versioning conventions already used by the theme rather than duplicating an existing registration under another name.

wp_enqueue_style(
    'example-theme-generated',
    get_theme_file_uri( 'assets/css/theme.css' ),
    array(),
    '1.0.0'
);

Call the registration in the appropriate front-end enqueue callback, as described by the WordPress asset guide. Change the version when the output changes or use the project’s existing build manifest. Do not link the SCSS source itself, and do not add a second hard-coded link that loads the same stylesheet twice.

Preserve the theme’s other responsibilities

Keep the required identifying header in the theme’s root style.css. Generating assets/css/theme.css does not replace the role of that header. If this is a child-theme customization, preserve the intended relationship with the parent’s styles and use the supported child-theme workflow rather than modifying parent files that an update can replace.

Review editor styling separately from front-end styling. A stylesheet registered for visitor pages is not automatically evidence that the block editor receives the same appearance. Follow the theme’s existing editor-style arrangement when the generated rules should also affect editing, and check whether that context needs a distinct entry stylesheet.

Fail the release when compilation fails

Use a one-shot build for release automation and check its exit status. Do not publish a previous successful output after a new SCSS edit fails. The example disables error CSS and source-map output for a simple delivery artifact; change that map policy deliberately if the project needs maps for debugging.

Watch mode can be convenient while developing, but it is not a process that a release job should wait on indefinitely. Keep development watching and production generation as separate commands. Preserve source and lockfiles so another environment can recreate the same stylesheet without installing a personal editor extension.

Verify the compiled result where visitors see it

Inspect the page’s stylesheet request, then check a .theme-note element’s computed padding and border in both layout directions where relevant. Confirm image and font URLs if the real source contains them. Coordinate the version change with caches so the page fetches the newly generated file.

The local CSS minifier can process the compiled CSS afterward, but it is not a WordPress SCSS compiler. Keep Sass compilation, WordPress asset registration and browser rendering as separate stages with evidence that each stage received the intended input.