How to use Tailwind CSS in Sugar customizations

In 13.3, we officially started to use Tailwind CSS. This library provides documented utility classes that behave as an API for styling. Of course, stylesheets will still be used for some occasions, but most of our styles can be moved into the template/controller/metadata files as classes. If you’re unfamiliar with Tailwind CSS, you can read more about it here.

How it’s setup

Tailwind CSS out of the box is driven by a JavaScript config file that manages: the files that will be considered during the compiling of the tailwind.css file (which houses all the classes used), extensions of the default API, or any other changes you’d like to make to default behavior.

The library of utilities is quite vast, and therefore the build pipeline has tree-shaking enabled by default to cut down on the outputted file size. This keeps builds as small as possible, and will only include what you need. However, this means that there may be classes that are not included in our production Tailwind CSS build, that may be desired in a Sugar customization. That’s ok! Moving forward there will be no dependency on Sugar’s implementation of Tailwind CSS utilities, and you’ll be able to build your own Tailwind CSS file that will only include the utilities you need.  

Please follow along with this example for getting Tailwind up and running in your customization, you can also check below a summary of the steps.

Getting started

To prepare this package for testing the output files, run yarn build:dev within this folder. This will generate an unminified bundle.css file. If you'd like to prepare this package for use in your Sugar instance, run yarn build to generate a production-ready, minified bundle.css file.

How to use TailwindCSS?

This framework includes utility CSS classes for almost any property you can think of. They have built on a shorthand syntax that keeps composition clean, and maintainable. For example, if you'd like to use a class in a standard JavaScript component, Handlebars template, or PHP metadata file, it would look like this:

<div class="flex items-center">
    <button class="border border-slate-200 font-semibold h-10 px-6 rounded-md text-slate-900" type="button">
        Hello!
    </button>
</div>

or directly in the tailwind.css file, using the @apply keyword:

.test-selector {
  @apply flex mt-4;    // display: flex; margin-top: 1rem;
}

This would result in a bundle.css file containing all the class definitions from the above snippets. Unminified, it would it look like the following:

.test-selector {
    display: flex;
}

.test-selector {
    align-items: center;
}

.test-selector {
    margin-top: 1rem;
}

/* ... etc*/

Installation

First, you'll want to create a zip of all the files required for the MLP. It is easiest to include only files pertaining to the uploaded package. If you have the zip package installed; you can execute the following from within this folder:

$  yarn package

or if you'd like to run the zip command directly:

$  zip tailwindcss-mlp-example.zip manifest.php -r Files/

This will generate the file tailwindcss-mlp-example.zip that you can then upload to your instance using Module Loader.

Note: If you're running MacOS, make sure that there are no .DS_Store files present in any of the folders and subfolders before creating the zip file, as this will cause issues when trying to upload the MLP.