Skip to content

Refactor README #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mcrumm merged 1 commit into from
Mar 27, 2026
Merged

Refactor README #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 64 additions & 69 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,16 @@
# DartSass

[![CI](https://github.com/CargoSense/dart_sass/actions/workflows/ci.yml/badge.svg)](https://github.com/CargoSense/dart_sass/actions/workflows/ci.yml)
**Install and run [Dart Sass](https://github.com/sass/dart-sass) using Elixir.**

Mix tasks for installing and invoking [sass](https://github.com/sass/dart-sass/).
[![Package](https://img.shields.io/hexpm/v/dart_sass?logo=elixir&style=for-the-badge)](https://hex.pm/packages/dart_sass)
[![Downloads](https://img.shields.io/hexpm/dt/dart_sass?logo=elixir&style=for-the-badge)](https://hex.pm/packages/dart_sass)
[![Build](https://img.shields.io/github/actions/workflow/status/CargoSense/dart_sass/ci.yml?branch=main&logo=github&style=for-the-badge)](https://github.com/CargoSense/dart_sass/actions/workflows/ci.yml)

## Installation

If you are going to build assets in production, then you add
`dart_sass` as a dependency on all environments but only start it
in dev:
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:

```elixir
def deps do
Expand All @@ -18,8 +20,7 @@ def deps do
end
```

However, if your assets are precompiled during development,
then it only needs to be a dev dependency:
If your application's assets are precompiled during development, configure DartSass as a dependency for the development environment only:

```elixir
def deps do
Expand All @@ -29,42 +30,36 @@ def deps do
end
```

Once installed, change your `config/config.exs` to pick your
dart_sass version of choice:
Next, update your application's `config/config.exs` to set [a Dart Sass version](https://github.com/sass/dart-sass/releases):

```elixir
config :dart_sass, version: "1.97.3"
```

Now you can install dart-sass by running:
You may now install Dart Sass by running:

```bash
$ mix sass.install
mix sass.install
```

And invoke sass with:
Invoke the `sass` executable by running:

```bash
$ mix sass default assets/css/app.scss priv/static/assets/app.css
mix sass default assets/css/app.scss priv/static/assets/app.css
```

If you need additional load paths you may specify them:
Additional load paths may be specified using the `--load-path` flag:

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

The executable may be kept at `_build/sass-TARGET`. However in most cases
running dart-sass requires two files: the portable Dart VM is kept at
`_build/dart-TARGET` and the Sass snapshot is kept at `_build/sass.snapshot-TARGET`.
Where `TARGET` is your system target architecture.
> [!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`).

## Profiles
## Configuring profiles

The first argument to `dart_sass` is the execution profile.
You can define multiple execution profiles with the current
directory, the OS environment, and default arguments to the
`sass` task:
DartSass requires an execution profile as its first argument. You may define multiple execution profiles using the current directory, the environment, and default arguments:

```elixir
config :dart_sass,
Expand All @@ -75,16 +70,14 @@ config :dart_sass,
]
```

When `mix sass default` is invoked, the task arguments will be appended
to the ones configured above.
Invoking `mix sass default` appends the task arguments to the ones configured above.

## Adding to Phoenix
## Using with Phoenix

To add `dart_sass` to an application using Phoenix, you need only four steps.
Note that installation requires that Phoenix watchers can accept `MFArgs`
tuples – so you must have Phoenix > v1.5.9.
> [!NOTE]
> Using DartSass with [Phoenix](https://phoenixframework.org) requires Phoenix v1.5.10 or newer.

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

```elixir
def deps do
Expand All @@ -95,8 +88,7 @@ def deps do
end
```

Now let's configure `dart_sass` to use `assets/css/app.scss` as the input file and
compile CSS to the output location `priv/static/assets/app.css`:
Next, configure DartSass to use `assets/css/app.scss` as the input file and set the output file to `../priv/static/assets/app.css`:

```elixir
config :dart_sass,
Expand All @@ -107,55 +99,58 @@ config :dart_sass,
]
```

> Note: if you are using esbuild (the default from Phoenix v1.6),
> make sure you remove the `import "../css/app.css"` line at the
> top of assets/js/app.js so `esbuild` stops generating css files.
> [!NOTE]
> If your application uses [esbuild](https://esbuild.github.io), remove `import "../css/app.css"` from your application's `assets/js/app.js`. This change will prevent esbuild from _also_ generating CSS files.

> Note: make sure the "assets" directory from priv/static is listed
> in the :only option for Plug.Static in your endpoint file at,
> for instance `lib/my_app_web/endpoint.ex`.
> [!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.
>
> ```elixir
> plug Plug.Static,
> at: "/",
> from: :my_app,
> only: ~w(assets favicon.ico robots.txt)
> ```

For development, we want to enable watch mode. So find the `watchers`
configuration in your `config/dev.exs` and add:
In development mode, configure Dart Sass' `--watch` flag in your application's `config/dev.exs` file:

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

Note we are embedding source maps with absolute URLs and enabling the file system watcher.
The configuration above also enables embedded source maps using aboslute URLs. Consult the [Dart Sass Command-Line Interface documentation](https://sass-lang.com/documentation/cli/dart-sass/) 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, back in your `mix.exs`, make sure you have an `assets.deploy`
alias for deployments, which will also use the `--style=compressed` option:
Finally, in your application's `mix.exs`, create or update the `assets.deploy` alias to include `sass` (in this example, configuring the output style):

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

## FAQ

### Watchers and Bash

In order to ensure graceful termination of the `sass` process when stdin closes, when the`--watch`
option is given then the sass process will be invoked by a bash script that will handle the
cleanup.

Note this script is not invoked on Windows platforms, so be aware that using `--watch` may leave
orphaned processes.

## Acknowledgements

This package is based on the excellent [esbuild](https://github.com/phoenixframework/esbuild) by Wojtek Mach and José Valim.
This package is based on [Wojtek Mach](https://github.com/wojtekmach)'s and [José Valim](https://github.com/josevalim)'s excellent [esbuild](https://github.com/phoenixframework/esbuild) installer.

## License

Copyright (c) 2021 CargoSense, Inc.

dart_sass source code is licensed under the [MIT License](LICENSE.md).
DartSass is freely available under the [MIT License](https://opensource.org/licenses/MIT).
Loading