tailwindcss-in-browser v0.1.1

A JavaScript library that enables you to build CSS directly in the browser using Tailwind CSS 4.

Installation

npm install tailwindcss-in-browser

Usage

import buildCss from "tailwindcss-in-browser";

const markup =
  '<div class="text-2xl text-teal-600 font-semibold">Hello, world!</div>';

// Tailwind CSS 4 configuration via CSS.
const configurationCss = `
  @theme {
    --font-size-2xl: 1.75rem;
    --font-size-2xl--line-height: 2.25rem;
  }
`;

buildCss(markup, configurationCss, {
  compileCssOptions: { addPreflight: false }, // Optional. Defaults to `true`.
  transformCssOptions: { minify: false }, // Optional. Defaults to `true`.
}).then((css) => {
  // `css` contains the generated Tailwind CSS styles.
});

This library is available as an ES module and works with both module bundlers and directly in browsers:

<script type="module">
  import buildCss from "https://unpkg.com/tailwindcss-in-browser";

  // ...
</script>

How it works

1. A function from Tailwind CSS 3 is used to extract class names from the markup. In Tailwind CSS 4, this is done by the Oxide engine, which is written in Rust, and requires a Node.js runtime.

2. Compiling the CSS using the extracted class names happens with Tailwind CSS 4, supporting its CSS-first configuration.

3. Lightning CSS is used to transform the compiled CSS for browser compatibility, matching the implementation of Tailwind CSS 4, but using lightningcss-wasm, so it can run in the browser.

API reference

Main function

buildCss()

The primary function for generating Tailwind CSS styles. It extracts class names from the markup, compiles them using Tailwind CSS 4, and transforms them with Lightning CSS for browser compatibility.

Returns: Promise<string> - The compiled and transformed CSS.

By default, Tailwind CSS Preflight styles are included, and the output CSS is minified. You can customize these behaviors via options. In case you need more granular control, you can use the utility functions below. Calling them separately in the order below (extractClassNameCandidates() → compileCss() → transformCss()) is equivalent to calling buildCss().

Tailwind CSS 4 configuration

Tailwind CSS 4 uses a CSS-based configuration format. Normally in this CSS file you would add @import "tailwindcss", which imports the following:

• the base/preflight layer,
• the default Tailwind CSS 4 theme;
• the components layer —yet to be implemented in Tailwind CSS 4—, and
• the utilities layer where the actual Tailwind CSS classes are defined.

When working with this library, all of the above is taken care of, so all you need to do is add your theme customizations with a @theme directive. E.g.:

@theme {
  /* Colors */
  --color-primary: #3b82f6;
  --color-secondary: #64748b;

  /* Typography */
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;

  /* Spacing */
  --spacing-4: 1rem;
  --spacing-8: 2rem;
}

Utility functions

extractClassNameCandidates()

Extracts Tailwind class names from markup.

Returns: string[] - Array of extracted class names.

compileCss()

Compiles CSS using Tailwind CSS 4.

Returns: Promise<string> - Compiled CSS

transformCss()

Transforms CSS for browser compatibility.

Returns: Promise<string> - Transformed CSS

Configuration options

CompileCssOptions

TransformCssOptions

Credits

• The technical foundation for running Tailwind CSS 4 in the browser was demonstrated by @dtinth in a blog post, which served as the basis for this implementation.
• This package was created with sponsorship from Acquia through work on Drupal's Experience Builder.