Utility-first CSS without a build step

#What "without a build step" actually means

A build step is any program that has to run between the file you edit and the file the browser loads. For utility CSS that program normally reads your HTML, finds the class names you used and writes a stylesheet that contains only those rules. It is a good design for large applications, but it means you cannot open an HTML file and start styling it. You need Node.js, a configuration file, a watcher in a terminal and a pipeline in production.

Monsoon predeclares the classes instead. The stylesheet you link already contains px-4, md:grid-cols-3, hover:bg-primary and the other 4,923 base classes, plus 10,237 variant classes. Nothing reads your markup, nothing generates CSS on the fly and nothing runs in the browser. You save the file and refresh.

#Your first page in one minute

Create an HTML file, add the stylesheet and start writing classes. This is a complete, valid page:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>My page</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/monsooncss">
</head>
<body class="bg-background text-foreground antialiased">
  <main class="mx-auto max-w-2xl px-6 py-16 space-y-6">
    <h1 class="text-4xl font-extrabold tracking-tight">Hello</h1>
    <p class="text-lg text-muted-foreground">Styled with utility classes and nothing else.</p>
    <a href="#" class="inline-block rounded-lg bg-primary text-primary-foreground px-4 py-2 font-medium hover:bg-primary/90">
      Read more
    </a>
  </main>
</body>
</html>

Open it straight from disk with a double click. It works the same from file://, from a local server and from production, because there is no difference between a development stylesheet and a production stylesheet.

#How a predeclared stylesheet stays small

If every utility had every variant, the file would be enormous. Monsoon keeps it at about 88.3 kB with brotli (145.4 kB with gzip) by generating each variant only for the utility groups where it is useful. This is a deliberate, documented choice rather than an accident:

• hover: exists for colors, opacity modifiers, shadows, opacity and transforms, because that is what people change on hover.
• focus:, focus-visible: and focus-within: exist for semantic colors, rings and outlines.
• sm: to 2xl: exist for layout: display, position, flex and grid, gaps, spacing, sizing and text size.
• dark: exists for palette colors, white, black and opacity modifiers. Semantic colors do not need it because they switch on their own.
• @xs: to @xl: container queries exist for the layout utilities you reach for inside components.

The class reference shows the variants of every class, and npx monsooncss classes --filter md: lists them in a terminal.

#What you give up, and the simple workarounds

A prebuilt file cannot know values you invent while writing markup. Three things are therefore not part of Monsoon:

• Arbitrary values such as w-[37px] are not in the file. They work with the optional monsoon.js script, or compiled by the purge CLI; otherwise use the nearest step of the scale, or a style attribute for a true one off.
• Stacked variants such as dark:hover: or md:hover:. Semantic colors already adapt to the color scheme, so hover:bg-primary covers most of the cases.
• The important modifier. Monsoon keeps its reset in a cascade layer and utilities at low specificity, so your own CSS wins without it.

Writing a few lines of your own CSS next to Monsoon is normal and encouraged. Custom properties make it pleasant, because the theme tokens are plain variables you can use anywhere:

.price-tag {
  background: var(--primary);
  color: var(--primary-foreground);
  clip-path: polygon(0 0, 92% 0, 100% 50%, 92% 100%, 0 100%);
}

#When to add a step back

Most sites can serve the full file forever: it is one cached request. If you care about every kilobyte, Monsoon ships an optional command that you run once before deploying. It scans your files and writes a stylesheet with only the rules they use. It is a convenience, not a requirement, and your source files do not change.

npx monsooncss purge "src/**/*.html" -o public/monsoon.css

Read the production guide for version pinning, caching and when purging is worth it.

#Frequently asked questions

#Keep reading