Sass in the Browser

Posted 7 July 2023 by Natalie Weizenbaum

Over Sass’s lifetime, we’ve seen many of the features we’ve pioneered adopted in the browser. CSS variables, math functions, and most recently nesting were all inspired by Sass. But running Sass itself as a compiler in the browser was never possible… until now.

With the release of Dart Sass 1.63, we’re officially adding support to the sass npm package for running directly in the browser. No longer do creators of playgrounds or web IDEs need to make server calls to compile their Sass. Now you can just load it up and use it right on your very page.

You can try it right now, in fact! Just open up your developer console and run this:

const sass = await import('https://jspm.dev/sass');
sass.compileString('a {color: #663399}');

How Else Can I Use It?How Else Can I Use It? permalink

We’ve done our best to make sure that Sass in the browser is usable as many ways as possible. It can be loaded using both CommonJS require() and ES6 import. It can be loaded by bundlers (we’ve tested with esbuild, Rollup, Vite, and webpack), or it can be loaded with no bundling at all directly in the browser.

The only caveat is that it does depend on the Immutable library, so if you’re using it without any bundling at all you’ll need to set up an import map so that it can find that dependency. But if you’re using a bundler or a CDN like JSPM that pulls in dependencies for you, you won’t need to worry about it.

The Dart Sass README is the canonical location for more detailed information about getting up and running with Dart Sass in the browser in any of the many ways it supports.

What APIs Are Available?What APIs Are Available? permalink

We’ve tried to make as much of the JavaScript API as possible available in the browser. Custom functions and importers are both supported, along with the full Sass value API. However, there are two categories of API that aren’t available in the browser:

  1. Any API that expects a filesystem to exist. This means that you can’t pass in a FileImporter, but it also means that the compile and compileAsync functions aren’t available since they take file paths. You’ll need to use compileString or compileStringAsync instead.

  2. The legacy JavaScript API. This API only exists for compatibility with the deprecated node-sass package. Since node-sass never supported running in the browser and this API has a much squishier distinction between loading from the filesystem and loading from other sources, we decided to just not support it in the browser at all.

Play Around With ItPlay Around With It permalink

Because Sass can now run directly in the browser, we’ve been able to add another long-awaited feature to the Sass website: the Sass Playground! This is a way to test out Sass directly in your browser, and since it’s hooked up to the Sass website’s deploy process it’ll always use the latest version with all the latest features.

The stylesheet in your playground is always saved to the playground URL, so you can easily share example stylesheets or use them to report bugs to the Sass team. Give it a try!

AcknowledgementsAcknowledgements permalink

I would like to thank the fine folks at OddBird for making all this a reality, particularly: