Using the Dart Sass transpiler

tips & tricks
,
1

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.

  1. In 2023, the Sass team deprecated Embedded Dart Sass in favor of Dart Sass. ↩︎

  2. 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. ↩︎

12 Likes
2

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
3

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.

4 Likes
4

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)?

5

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.

3 Likes
6

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

2 Likes
7

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

8

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…

1 Like
9

Because it is built-in to the extended edition.

Yes.

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

10

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

11

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

12

I wondered if it would be worth adding to the list the option on Linux of installing sass-embedded - npm which as I understand it includes the dart build of dart-sass (the naming scheme does seem somewhat byzantine). It does then need the PATH manually setting to point to the package in node_modules (e.g. node_modules/sass-embedded-linux-x64/dart-sass) but the advantage for us is that it’s managed by npm / package.json for updating, as we cannot use snap or brew on our production servers.

13

I didn’t know this package was available again.

When the Dart Sass team changed the embedded protocol in 1.63.0, they did not roll a release for Embedded Sass Host, also known as embedded-host-node, or sass-embedded in the npm registry. Nor did they roll a release for 1.63.1, so I concluded this package was abandoned along with the dart-sass-embedded Homebrew package, which was a bit of a mess.

As you described, the npm install sass-embedded command does not place the “binary” in your PATH. Similar to using curl on GitLab as shown in our Dart Sass documentation, you may have to move the “binary” to a location already in your path, or modify the PATH variable.

I quote the word “binary” because it’s not a binary. It’s a script (batch file on Windows) that calls Dart, passing the path to the sass.snapshot file as an argument. This file structure is the same across for all Dart Sass implementations, excluding the Dart Sass npm package, which doesn’t support the embedded protocol.

Given the history here, I am reluctant to document this approach, and it definitely should not be documented as an alternative to the the package managers.

In your case, I think the safest (best chances of forward compatibility) approach is to use curl to download Dart Sass. Again, see this example.

2 Likes
14

If you use mise to manage dart-sass, Hugo will fail to start.

This is .mise.toml

[tools]
"npm:dart-sass" = "latest"

This is the output:

$ dart-sass --version
1.25.0 compiled with dart2js 2.7.0

$ which dart-sass
/home/hentioe/.local/share/mise/shims/dart-sass

$ hugo server -D
port 1313 already in use, attempting to use an available port
Watching for changes in /home/hentioe/code/hugo-blog/{archetypes,assets,content,data,i18n,layouts,package.json,static,themes}
Watching for config changes in /home/hentioe/code/hugo-blog/hugo.toml, /home/hentioe/code/hugo-blog/themes/my-theme/hugo.toml
Start building sites … 
hugo v0.127.0 linux/amd64 BuildDate=unknown

Built in 155 ms
Error: error building site: TOCSS-DART: failed to transform "/scss/main.scss" (text/x-scss): "<stream>:1:1": proto: cannot parse invalid wire-format data

mise is a version management tool similar to asdf that can manage NPM package versions without the need for package.json or npm i -g.

I know mise isn’t a very common tool, but it would be nice if it could be fixed.

15

Hugo needs the embedded Sass protocol and that is not included in the npm version.

1 Like
16

As @frjo described, there’s nothing to fix.

1 Like