tailwindcss-in-browser

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>

Note for Vite users

If you use Vite, add the following to your config:

{
  optimizeDeps: {
    exclude: ["tailwindcss-in-browser"],
  },
};

This workaround is needed until vitejs/vite#8427 is fixed.

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.

Parameter	Type	Description
markup	string	The HTML markup containing Tailwind classes.
configurationCss	string	CSS configuration for Tailwind CSS 4 (see Tailwind CSS 4 configuration).
options	object	Optional configuration object.
options.compileCssOptions	CompileCssOptions	Options for CSS compilation.
options.transformCssOptions	TransformCssOptions	Options for CSS transformation.

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.

Parameter	Type	Description
markup	string	HTML markup to analyze.

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

compileCss()

Compiles CSS using Tailwind CSS 4.

Parameter	Type	Description
classNameCandidates	string[]	Array of class names to process.
configurationCss	string	Tailwind v4 configuration CSS.
options	CompileCssOptions	Compilation options.

Returns: Promise<string> - Compiled CSS

transformCss()

Transforms CSS for browser compatibility.

Parameter	Type	Description
css	string	CSS to transform.
options	TransformCssOptions	Transformation options.

Returns: Promise<string> - Transformed CSS

Configuration options

CompileCssOptions

Option	Type	Default	Description
addPreflight	boolean	true	Whether to include Tailwind's Preflight styles.

TransformCssOptions

Option	Type	Default	Description
minify	boolean	true	Whether to minify the output CSS.

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.