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 -r /opt/build/repo/node_modules/sass-embedded-linux-x64/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.58.3"
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. ↩︎

7 Likes

Thanks for this. A really handy and easy to follow guide and thankfully a pain free switch to using Dart sass.

I was already finding some of the newer CSS, like the min() function, was causing errors using libsass and with all the new CSS coming out over the past year or so such problems/limitations would only have increased.

Still, although simple, hopefully Dart sass is integrated into Hugo in the near future. That single binary simplicity was one of the main attractions for me when I first started using Hugo.

2 Likes

Excellent guide!

The css min() and sass min() etc. can clash, a simple solution is to write Min() if you want the css version. sass is case sensitive but css is not.

3 Likes