Using Sass and Bulma in Dart Web Projects

Post date: Feb 10, 2019 2:25:3 PM

Dart Web offers a great foundation for writing maintainable web applications. The Dart Web Get Started page contains pretty much everything you need to start writing web applications in no time.

But one thing that I found to be missing from the docs was how to set up my project to use existing CSS libraries such as Bulma, and Sass. Sure, you could just copy the minified css file from your favourite library into your web assets directory and link to it from the html page... but Dart actually has a better option!

With the saas_builder, you can set up your build to automatically generate a single minified css file from all your custom css and scss files. It works perfectly well with hot-reloading, so just like you can change your Dart code and immediately see the result of your changes in the browser, you can also modify the css and scss files and immediately see how it looks like!

In this blog post, I will describe how you can set Sass up in 5 minutes or less, and as an example, I'll use the Bulma css library to show how Sass allows you to customize Bulma and include only the parts of the library that you want to use to make your application look beautiful and light!

All code shown in this post can be found on GitHub: https://github.com/renatoathaydes/dart-sass-bulma-example

Pre-requisites

I'll assume you have already set up Dart in your machine as described in the Get Started page of the Dart Web documentation.

I do not attempt to explain how to use Sass or Bulma, just how to use them in the context of a Dart project.

If you need to learn Sass first, go to the Sass guide.

If you need to learn Bulma, start with the Bulma Overview.

Using the Sass builder

Let's start from the beginning. If you don't already have a project, create one using stagehand:

mkdir my-project

cd my-project

stagehand web-simple

Open the pubspec.yaml file. Add a dev dependency on sass_builder (you may want to check for the latest version on pub). Your dev_dependencies section should look like this:

dev_dependencies:

build_runner: ^1.1.2

build_web_compilers: ^1.0.0

sass_builder: ^2.1.2

Run pub get to fetch the dependencies, then replace the web/styles.css file with a new, web/main.scss file:

pub get

rm web/styles.css

touch web/main.scss

Add something to web/main.scss to make sure the Sass pre-processor is working:

$primary-color: #333;

$default-font-size: 2em;

body {

font-size: $default-font-size;

}

#output {

padding: 20px;

text-align: center;

color: $primary-color;

}

Don't forget to change the link in web/index.html to main.css (notice it's main.css, not main.scss - Sass will generate a css file from your scss file so the browser can understand it).

Run webdev:

webdev serve --live-reload

Wait until it prints Serving `web` on http://localhost:8080, then open that URL in your browser.

You should see something like this:

If you change something in the web/main.scss file, you'll notice the browser will automatically refresh the page with your changes.

Once you're happy with the styles, build a production release:

webdev build

You'll notice that it produces a minified css file at build/main.css. Perfectly done!

Using all of Bulma

Bulma is an awesome css library that makes it very easy to make your web applications and websites look modern and stylish. Bulma is built as several Sass modules which can be imported separately.

But before we see how we can choose which modules to use, let's just import the whole library, so that later we can compare the size of the generated css file.

First of all, to keep things organized, let's move our custom css from the main file to a sub-module, so that the main file is used only to import the resources we want to use.

So, create a file at web/_sub.scss and copy the contents of web/main.scss into it:

cp web/main.scss web/_sub.scss

Now, change the contents of web/main.scss to the following:

@import "package:bulma_sass/scss/bulma";

@import "_sub.scss";

You might notice an error at this point:

[SEVERE] sass_builder on web/main.scss:

Error: "package:" URLs aren't supported on this platform.

╷

1 │ @import "package:bulma_sass/scss/bulma";

│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

╵

- 1:9 root stylesheet

This is because the Bulma package cannot be found by the Sass builder until you add it as a dev dependency (I don't think this is supposed to be needed, but anyway, I filed an issue with the sass_builder project - it should at least give a proper error message):

dev_dependencies:

build_runner: ^1.1.2

build_web_compilers: ^1.0.0

sass_builder: ^2.1.2

bulma_sass: '>=0.7.1'

As we've updated our project's dependencies, we need to again run pub get to fetch the dependencies and then restart webdev:

pub get

webdev serve --live-reload

We can now check in the browser what the app looks like and how much overhead Bulma is adding:

As you can see, the main.css file now grew to almost 190,000 bytes. If we had a huge app that needed all of Bulma, that would be no problem, probably... but we should avoid having such large assets when most of it is things we're not using yet.

Using Bulma Modules

Let's suppose all we wanted for now was to use a Bulma Hero Banner to make the top banner of our web page impressive.

We could create the banner via Dart code, but to keep things simple, let's do it directly on the HTML web/index.html.

Replace:

With:

Dart Web with Bulma

</h1>

An example of using the Sass_builder with Bulma.

</h2>

</div>

</section>

</section>

The result should look like this:

Not bad! Now, let's only import the Bulma modules required for the hero banner to work (plus some of the basic functionality which is almost always required for other modules to work).

Change the web/main.scss file to contain the following:

// Bulma modules

@import "package:bulma_sass/scss/utilities/_all";

@import "package:bulma_sass/scss/base/_all";

@import "package:bulma_sass/scss/elements/_content";

@import "package:bulma_sass/scss/elements/_title";

@import "package:bulma_sass/scss/layout/hero";

// Custom SCSS

@import "_sub.scss";

Now, we can see that the main.css file became much smaller, around 45,000 bytes:

You can find out what is possible to import from the scss file in the dart_bulma_sass project (the file tree should match closely the structure of the Bulma Docs).

Notice that, to make it easier to import related elements, every top folder contains a file called _all.scss which can be used to import everything in that folder.

Customizing Bulma

One last thing we may want to do when we start using a css library like Bulma is to customize it so that our app doesn't look like everyone else's.

To customize Bulma, you just need to set the variables you want to modify in the scss file before importing Bulma.

For example, we could change the info colors, which we used in the hero banner above, by modifying web/main.scss as follows:

// Bulma customizations

$info: darkgreen;

$info-invert: lightyellow;

// Bulma modules

@import "package:bulma_sass/scss/utilities/_all";

@import "package:bulma_sass/scss/base/_all";

@import "package:bulma_sass/scss/elements/_content";

@import "package:bulma_sass/scss/elements/_title";

@import "package:bulma_sass/scss/layout/hero";

// Custom SCSS

@import "_sub.scss";

The page will now look like this:

Conclusion

In this blog post, I showed how easy it is to use Sass in Dart Web projects. We also added Bulma to the project without ever having to manually download any resources. The Dart package manager, pub, itself handles that with versioning, so upgrading should be as easy as running pub upgrade.

Unlike with some other toolchains, in Dart builds everything is handled uniformly via builders, so that as long as someone wrote a builder for a tool, integrating that tool with Dart projects should be completely trivial. Luckily, both Sass and Bulma are covered.

Thanks for reading.