#Managing Build Size

Since Cirrus is built with customization in mind, it makes sense for the framework to allow features to be enabled, disabled, or modified. One of the pain point for some CSS frameworks is its size. Cirrus by no means is a hefty CSS framework, but reduction in file size would help improve page speeds on slower connections and smaller devices.

#File Size

As of now, the different builds of Cirrus clock in at the following sizes:

Flavor	Minified	Gzip	Brotli
Core
Ext (Full)
All

Cirrus comes in 3 preset builds that cover the requirements of most users to balance the tradeoffs between build size and feature set. You can read more about the differences between these builds in the development guide.

Some developers, however, may require a granular way to toggle which classes are generated and which are not to remove as much unused classes as possible. There are virtually hundreds of ways to customize your build of Cirrus through the config file. The docs below goes over all the ways you can manage your file size when building Cirrus for your project.

In short, it is recommended to remove as many unused styles as possible for optimal performance.

#Using Purge CSS

For a quick way to drastically reduce the amount of unused CSS classes, you can use third-party tools like PurgeCSS to tree-shake unused Cirrus styles in your project. Applying minification on top of the CSS file after purging would further decrease the file size. Out of all the methods described on this page, this would yield the smallest file size.

To find out how to integrate this into Cirrus and your project, check out the PurgeCSS docs.

Note Before Use

If you are using front-end frameworks like React, Angular, Vue, etc., PurgeCSS will not dynamically analyze and evaluate your template code to determine which classes to keep and which to toss out. PurgeCSS simply checks to see if the class name appears in it its entirety within the file. If it does, it will skip removing the class.

What this means is that if you do dynamically generate your class names, make sure that all class names you intend to use are in its whole form and not broken up/concatenated. PurgeCSS won't be able to match for those class names and will unintentionally purge them from your stylesheets.

❌ Do not fragment the class names.

<div className={`text-${isError ? 'danger' : 'success'}`}>...</div>

✅ Write class names in its entirety.

<div className={isError ? 'text-danger' : 'text-success'}>...</div>

#Disabling Features

This is perhaps one of the quickest ways to reduce your Cirrus build size. Cirrus comes with different configurations with different features enabled, but you can optimize even further by selecting the ones you know you will use. All of the available configuration can be easily found in the _config.scss file.

In your project, import the Cirrus library and specify the enabled and disabled features similar to what's shown below:

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        excludes: (
            'ABSOLUTES',
            'OVERFLOW',
            'POSITION',
        ),
    ),
);

Currently, every type of class found inside the components and utils folders in the repository can be used inside the includes and excludes lists. The only exception is the letter spacing util classes found inside base/fonts.scss which can also be used in these lists.

Below is how reducing the number of enabled features will affect build size (with all viewports enabled).

#Disabling Viewport Variants

Some classes support viewport variants where it behaves differently depending on the current screen size. This

In your project, import the Cirrus library and specify the enabled and disabled viewports similar to what's shown below:

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        viewports: (
            CLEARFIX: false,
            DISPLAY: false,
            FLEX: false,
        )
    ),
);

All supported viewport flags can be found in the cirrus-all build configuration here.

Below is how reducing the number of enabled viewport variants will affect build size.

#Limiting Color Palette

Some classes support viewport variants where it behaves differently depending on the current screen size. This

In your project, import the Cirrus library and specify the enabled and disabled viewports similar to what's shown below:

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        colors: (
            'teal': null,
            'indigo': null,
        )
    ),
);

All supported viewport flags can be found in the cirrus-all build configuration here.

Below is how reducing the number of colors will affect build size (with all viewports and features enabled). Note that there are 12 semantic colors and 91 extended colors.

#Limiting Viewports

We can limit the build size by removing some of the breakpoints that we generate classes for entirely. Note that removing too many may break some of the styles that relied on existing breakpoints to work. Therefore this is not as recommended of a setting to toggle if you're looking to save on build size.

In your project, import the Cirrus library and disable viewports by setting the existing viewport widths and pairs to null and specifying the ones you want in the extend section:

@use "cirrus-ui/src/cirrus-ext" as * with (
    $config: (
        breakpoints: (
            widths: null,
            breakpoint-pairs: null,
        ),
        extend: (
            breakpoints: (
                widths: (
                    'tablets': '640px',
                    'laptops': '1024px',
                )
            )
        )
    ),
);

Below is how reducing the number of breakpoints would affect the build size. By default Cirrus comes with 4 breakpoints specified.