Guide

Installation

Install the package:

npm install @studiometa/tailwind-config@alpha --save-dev

Usage

Import the configuration in your project's tailwind.config.js file.

// As is with no custom configuration
module.exports = require('@studiometa/tailwind-config');

// By adding the package's configuration as a preset and overriding it based on your project's needs
module.exports = {
  presets: [
    require('@studiometa/tailwind-config')
  ],
  // ...
}

TIP

preset extends the tailwindCSS 's base config object. If some parts of your tailwind config are redundant between projects, it can be a good strategy to load them from a preset.

Then, add the Tailwind directives in your global app.scss file:

// Import Tailwind's base the your project's base
@tailwind base;
// @import 'base/...';

// Import Tailwind's components then your project's components
@tailwind components;
// @import 'components/...';

// Import Tailwind's utilities then your project's utilities
@tailwind utilities;
// @import 'utilities/...';

WARNING

Do not forget to configure Purge CSS in your project to remove all unused classes from the generated CSS files.

How to and best practices

Responsive

Tailwind uses a mobile first breakpoint system. It is recommended to use the utility classes unprefixed to target mobile and override them at larger breakpoints.

<div class="text-center s:text-left m:text-right"></div>

For behaviors related to a specific breakpoint it is recommended to undo this behavior by using a utility class that reapplies the basic behavior on a larger breakpoint.

<div class="bg-teal m:bg-red l:bg-teal"></div>

Custom utility classes

First method: Add it in the SCSS files

To manage the import of custom utility classes on Tailwind using a preprocessor you should place them in separate files and import them after Tailwind's utilities imports to avoid specificity issues.

@tailwind base;
@tailwind components;
@tailwind utilities;
@import 'utilities/custom-utility';

To create custom utility classes that can be used with the breakpoints defined in our configuration you should declare these utility classes in a @responsive directive.

@tailwind base;
@tailwind components;
@tailwind utilities;

@responsive {
  @variants hover, focus {
    .rotate-0 {
      transform: rotate(0deg);
    }
    .rotate-90 {
      transform: rotate(90deg);
    }
    .rotate-180 {
      transform: rotate(180deg);
    }
    .rotate-270 {
      transform: rotate(270deg);
    }
  }
}

The responsive versions of these utility classes will be automatically generated by Tailwind using the breakpoints entered in the configuration file.

<div class="rotate-0 hover:rotate-90"></div>

You can read the documentation on variants management for more detailed informations.

Second method: By creating a plugin

We can add custom utilities with plugin. The following example generates the same classes as in the first method:

// tailwind.config.js
module.exports = {
  plugins: [
    ({ addUtilities }) => {
      const newUtilities = {
        '.rotate-0': {
          transform: 'rotate(0deg)',
        },
        '.rotate-90': {
          transform: 'rotate(90deg)',
        },
        '.rotate-180': {
          transform: 'rotate(180deg)',
        },
        '.rotate-270': {
          transform: 'rotate(270deg)',
        },
      };

      addUtilities(newUtilities, ['responsive', 'hover']);
    },
  ],
};

Read the documentation for more informations on plugins.

Directives and Functions

@apply

Apply is useful for component extraction when a pattern repeats itself. For buttons for example, it allows to centralize the properties of a component.

These declarations can be used alongside classic CSS declarations.

.btn {
  @apply font-bold py-2 px-4 rounded;
}
.btn-blue {
  @apply bg-blue-500 text-white;
}
.btn-blue:hover {
  @apply bg-blue-700;
  transform: translateY(-1px);
}

It is necessary to use interpolation to add !important to styles applied via the directive @apply:

.btn {
  @apply font-bold py-2 px-4 rounded #{!important};
}

The @apply directive cannot be used for statements about elements states or elemenrs responsiveness. Example of what you can't do:

.btn {
  @apply hover:bg-blue-500;
  @apply m:inline-block;
}

@variants

It is possible to generate states utilities for our own utility classes by wrapping them in an @variants directive.

@variants focus, hover {
  .rotate-0 {
    transform: rotate(0deg);
  }
  .rotate-90 {
    transform: rotate(90deg);
  }
}

This will generate the following CSS:

.rotate-0 {
  transform: rotate(0deg);
}
.rotate-90 {
  transform: rotate(90deg);
}

.focus\:rotate-0:focus {
  transform: rotate(0deg);
}
.focus\:rotate-90:focus {
  transform: rotate(90deg);
}

.hover\:rotate-0:hover {
  transform: rotate(0deg);
}
.hover\:rotate-90:hover {
  transform: rotate(90deg);
}

It is important to keep in mind that state variations will be generated in the order in which they are declared.

Finally, it is possible to generate customized variations to meet more specific needs.

@responsive

It is possible to generate utility classes using the breakpoints defined in the configuration file with the @responsive directive.

@responsive {
  .bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
}

This will generate the following CSS:

.bg-gradient-brand {
  background-image: linear-gradient(blue, green);
}

/* ... */

@media (min-width: 768px) {
  .s\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}

@media (min-width: 1024px) {
  .m\:bg-gradient-brand {
    background-image: linear-gradient(blue, green);
  }
  /* ... */
}

/*... */

@screen

Instead of writing media queries with pixel values it is possible to use the @screen directive and refer to a breakpoint by its name. If we have a breakpoint s at 768px it's possible to use it in the following way:

@screen s {
  /* ... */
}

theme()

The theme() function allows us to access the values entered in our configuration file.

.content-area {
  height: calc(100vh - theme('spacing.12'));
}

.btn-blue {
  background-color: theme('colors.blue.500');
}