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.