From ea2fa6facf10f236a1a72152654ff3c83785ab59 Mon Sep 17 00:00:00 2001 From: Jason Garber Date: Wed, 25 Mar 2026 10:18:34 -0400 Subject: [PATCH] Refactor README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates `README.md` with a bunch of wording tweaks and updates the overall organization and aesthetics (insofar as Markdown has aesthetics!) to align with some of CargoSense’s other open-source repositories. The resulting content should convey all of the same information. --- README.md | 133 ++++++++++++++++++++++++++---------------------------- 1 file changed, 64 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 007dab4..c967474 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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-`. In most cases, running Dart Sass requires the portable Dart virtual machine (`_build/dart-`) and the Sass snapshot (`_build/sass.snapshot-`) where `` 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, @@ -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 @@ -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, @@ -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).