DartSass

Install and run Dart Sass using Elixir.

Installation

Add DartSass to your project's dependencies in mix.exs and run mix deps.get.

If your application builds assets in production, configure DartSass as a runtime application in development:

def deps do
  [
    {:dart_sass, "~> 0.7", runtime: Mix.env() == :dev}
  ]
end

If your application's assets are precompiled during development, configure DartSass as a dependency for the development environment only:

def deps do
  [
    {:dart_sass, "~> 0.7", only: :dev}
  ]
end

Next, update your application's config/config.exs to set a Dart Sass version:

config :dart_sass, version: "1.97.3"

You may now install Dart Sass by running:

mix sass.install

Invoke the sass executable by running:

mix sass default assets/css/app.scss priv/static/assets/app.css

Additional load paths may be specified using the --load-path flag:

mix sass default assets/css/app.scss --load-path=assets/node_modules/bulma priv/static/assets/app.css

Note

The sass executable may be installed to _build/sass-<arch>. In most cases, running Dart Sass requires the portable Dart virtual machine (_build/dart-<arch>) and the Sass snapshot (_build/sass.snapshot-<arch>) where <arch> is your system's architecture (e.g. linux-arm64).

Configuring profiles

DartSass requires an execution profile as its first argument. You may define multiple execution profiles using the current directory, the environment, and default arguments:

config :dart_sass,
  version: "1.97.3",
  default: [
    args: ~w(css/app.scss ../priv/static/assets/app.css),
    cd: Path.expand("../assets", __DIR__)
  ]

Invoking mix sass default appends the task arguments to the ones configured above.

Using with Phoenix

Note

Using DartSass with Phoenix requires Phoenix v1.5.10 or newer.

First, add Phoenix as a dependency to your application's mix.exs:

def deps do
  [
    {:phoenix, "~> 1.7.14"},
    {:dart_sass, "~> 0.7", runtime: Mix.env() == :dev}
  ]
end

Next, configure DartSass to use assets/css/app.scss as the input file and set the output file to ../priv/static/assets/app.css:

config :dart_sass,
  version: "1.97.3",
  default: [
    args: ~w(css/app.scss ../priv/static/assets/app.css),
    cd: Path.expand("../assets", __DIR__)
  ]

Note

If your application uses esbuild, remove import "../css/app.css" from your application's assets/js/app.js. This change will prevent esbuild from also generating CSS files.

Note

Be sure to add assets (alongside other files from priv/static) to Plug.Static's only filter in your application's endpoint.ex file.

plug Plug.Static,
  at: "/",
  from: :my_app,
  only: ~w(assets favicon.ico robots.txt)

In development mode, configure Dart Sass' --watch flag in your application's config/dev.exs file:

config :my_app,
  # …
  watchers: [
    sass: {
      DartSass,
      :install_and_run,
      [:default, ~w(--embed-source-map --source-map-urls=absolute --watch)]
    }
  ]

The configuration above also enables embedded source maps using aboslute URLs. Consult the Dart Sass Command-Line Interface documentation for a complete list and description of supported options.

Note

When using the --watch option, the sass process is invoked using a Bash script to ensure graceful termination of the sass process when stdin closes. This script is not invoked on Windows platforms, so using the --watch option may result in orphaned processes.

Finally, in your application's mix.exs, create or update the assets.deploy alias to include sass (in this example, configuring the output style):

defp aliases do
  [
    # …
    "assets.deploy": [
      "esbuild default --minify",
      "sass default --no-source-map --style=compressed",
      "phx.digest"
    ],
    # …
  ]
end

Acknowledgements

This package is based on Wojtek Mach's and José Valim's excellent esbuild installer.

License

DartSass is freely available under the MIT License.