Using the Dart Sass transpiler

jmooring · December 12, 2022, 11:03pm

Last updated: 2023-06-22T17:38:47-07:00

This information is now included in the Hugo documentation.

The extended version of Hugo includes LibSass to transpile Sass to CSS. In 2020, the Sass team deprecated LibSass in favor of Dart Sass.

Use the latest features of the Sass language by installing Dart Sass in your development and production environments.

Installation overview

Dart Sass is compatible with Hugo v0.114.0 and later.

If you have been using Embedded Dart Sass^[1] with Hugo v0.113.0 and earlier, uninstall Embedded Dart Sass, then install Dart Sass. If you have installed both, Hugo will use Dart Sass.

If you install Hugo as a Snap package there is no need to install Dart Sass. The Hugo Snap package includes Dart Sass.

Installing in a development environment

When you install Dart Sass somewhere in your PATH, Hugo will find it.

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

You may also install prebuilt binaries for Linux, macOS, and Windows.

Run hugo env to list the active transpilers.

Installing in a production environment

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

GitHub Pages

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

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

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

GitLab Pages

To install Dart Sass for your builds on GitLab Pages, the .gitlab-ci.yml file should look something like this:

variables:
  HUGO_VERSION: 0.114.0
  DART_SASS_VERSION: 1.63.5
  GIT_DEPTH: 0
  GIT_STRATEGY: clone
  GIT_SUBMODULE_STRATEGY: recursive
  TZ: America/Los_Angeles
image:
  name: golang:1.20-buster
pages:
  script:
    # Install Dart Sass
    - curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz
    - cp -r dart-sass/* /usr/local/bin
    - rm -rf dart-sass*
    # Install Hugo
    - curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - apt install -y ./hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    - rm hugo_extended_${HUGO_VERSION}_linux-amd64.deb
    # Build
    - hugo --gc --minify
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Netlify

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

[build.environment]
HUGO_VERSION = "0.114.0"
DART_SASS_VERSION = "1.63.5"
TZ = "America/Los_Angeles"

[build]
publish = "public"
command = """\
  curl -LJO https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  tar -xf dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  rm dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz && \
  export PATH=/opt/build/repo/dart-sass:$PATH && \
  hugo --gc --minify \
  """

Example

To tranpile with Dart Sass, set transpiler to dartsass in the options map 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 }}

Miscellaneous

If you build Hugo from source and run mage test -v, the test will fail if you install Dart Sass as a Snap package. This is due to the Snap package’s strict confinement model.

In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. ↩︎
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. ↩︎

Horbes · February 11, 2023, 7:29am

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.

frjo · February 11, 2023, 11:03am

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.

bwintx · June 20, 2023, 12:52pm

Given the compatibility of Hugo 0.114.0+ with how Embedded Dart Sass is packaged within the Dart Sass binary as of Dart Sass 1.63.0, would your instructions for everything other than the Hugo Snap package now be the same except for installing dart-sass rather than dart-sass-embedded (or dart-sass-embedded@1.62.1 in the case of Homebrew)?

jmooring · June 20, 2023, 1:54pm

I have a checklist of items to update, including this Tips & Tricks article. But there’s no rush. I would prefer to wait until things settle down on the Sass side. Their changes were… abrupt.

jmooring · June 21, 2023, 8:04am

I’ve edited the original posting to reflect the transition from Embedded Dart Sass to Dart Sass.

bwintx · June 21, 2023, 10:12am

Yes, I see, here and in #1921. Good show!

bradbice · June 27, 2023, 10:11pm

I had to fix my Dart SDK by using (use at your own need/risk):

brew tap --repair
brew remove dart
brew update
brew install dart-lang/dart/dart
brew install sass/sass/sass

Now hugo env shows this:

hugo v0.114.1+extended darwin/arm64 BuildDate=unknown
GOOS="darwin"
GOARCH="arm64"
GOVERSION="go1.20.5"
github.com/sass/libsass="3.6.5"
github.com/webmproject/libwebp="v1.2.4"
github.com/sass/dart-sass/protocol="2.1.0"
github.com/sass/dart-sass/compiler="1.63.6"
github.com/sass/dart-sass/implementation="1.63.6"

Why is libsass still referenced? Is that ok? My hugo build seems fine…

jmooring · June 27, 2023, 10:13pm

Because it is built-in to the extended edition.

Yes.

Yes, I saw a brew/sass issue about this somewhere. Not our problem.

bwintx · June 29, 2023, 7:11pm

Another possibility — a shell script for installing both Hugo and Dart Sass on macOS or Linux/WSL (no PowerPoint version, sorry):

jmooring · September 27, 2023, 10:33pm

2 posts were split to a new topic: Help with Dart Sass installation on Mac