Using the Dart Sass transpiler

The extended version of Hugo includes LibSass to transpile Sass to CSS.

From the LibSass home page:

LibSass is now deprecated—new projects should use Dart Sass instead.

Including the Dart Sass transpiler, in the same way we include the LibSass transpiler, may be possible in the future, but you do not have to wait.

Installation

Local development

When you install the Dart Sass transpiler somewhere in your PATH, Hugo will find it. You can install a prebuilt binary, or use a package manager.

Package manager OS Site Installation
Chocolatey Windows chocolatey.org choco install dart-sass-embedded
Scoop Windows scoop.sh scoop install dart-sass-embedded
Snap Linux snapcraft.io sudo snap install dart-sass-embedded
Homebrew macOS, Linux brew.sh brew install sass/sass/dart-sass-embedded

The Hugo Snap package includes the Dart Sass transpiler. You do not need to install the transpiler.

CI/CD deployment

For CI/CD deployment (e.g., GitHub Pages, Netlify, etc.) you must edit the workflow to install the Dart Sass transpiler before Hugo builds the site[1]. Some providers allow you to use one of the package managers above, or you can download and extract the prebuilt binary.

GitHub Pages

To install the Dart Sass transpiler for your builds on GitHub Pages, add this step to the GitHub Pages workflow file:

- name: Install Dart Sass Embedded
  run: sudo snap install dart-sass-embedded

If you are using GitHub Pages for the first time with your repository, GitHub provides a starter workflow for Hugo that includes the Dart Sass transpiler. This is the simplest way to get started.

Netlify

To install the Dart Sass transpiler for your builds on Netlify, the netlify.toml file should look something like this:

[build]
publish = "public"
command = """\
  npm install sass-embedded-linux-x64@${DART_SASS_VERSION} && \
  mkdir -p /opt/build/repo/node_modules/.bin && \
  cp /opt/build/repo/node_modules/sass-embedded-linux-x64/dart-sass-embedded/dart-sass-embedded /opt/build/repo/node_modules/.bin && \
  dart-sass-embedded --version && \
  hugo --gc --minify \
  """

[build.environment]
HUGO_VERSION = "0.108.0"
DART_SASS_VERSION = "1.56.2"
TZ = "America/Los_Angeles"

You can also use the Homebrew package manager to install the Dart Sass transpiler, but the installation is slow (90 seconds). The npm method described above takes 5 seconds, and Netlify caches the executable for future builds.

Verification

With Hugo v0.108.0 and later, run hugo env to verify that the Dart Sass transpiler is available to Hugo.

Usage

To use the Dart Sass transpiler while building your site, specify the transpiler in the options passed to resources.ToCSS. For example:

{{ $opts := dict "transpiler" "dartsass" "targetPath" "css/style.css" }}
{{ with resources.Get "sass/main.scss" | toCSS $opts | minify | fingerprint }}
  <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
{{ end }}

Testing

Add this to your Sass file:

@use "sass:math";

body {
  font-size: math.div(144px, 2);
}

It will fail with LibSass. With Dart Sass your font size will be 72px.

Miscellaneous

If you compile Hugo locally, and run mage test -v, the test will fail if you are using the Snap package. This is probably due to the Snap package’s strict confinement.


  1. You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set useResourceCacheWhen to never in your site configuration, and (c) you add and commit your resources directory to your repository. ↩︎

4 Likes