eleventy-plugin-tailwindcss-4

v3.0.0

Published

17 days ago

An Eleventy plugin to process Tailwind CSS

0High
0Medium
0Low

dwkns

Eleventy Plugin TailwindCSS 4

An Eleventy plugin to make it easier to use Tailwind 4.0.x with Eleventy 3.0.x

Version 3.0

ESM-only. Watches @imported CSS files for changes. Uses async fs operations and PostCSS under the hood.

Installation & configuration

Install eleventy-plugin-tailwindcss-4 into your Eleventy project.

$ npm i eleventy-plugin-tailwindcss-4

Create a Tailwind source/config file

In Tailwind 4 this file acts both as your source CSS file and the Tailwind Config file.

/* src/css/tailwind.css */
@import 'tailwindcss';

Configure Eleventy

Import the plugin in your configuration file eleventy.config.js.

ESM (recommended)

import tailwindcss from 'eleventy-plugin-tailwindcss-4'

eleventyConfig.addPlugin(tailwindcss, {
  input: 'css/tailwind.css' // required
} );

input Is the only required option. It is your Tailwind source/config file and is relative to your Eleventy input folder. All the options are optional see below.

CJS

This is an ESM package. In a CommonJS config file, use a dynamic import():

module.exports = async function (eleventyConfig) {
  const { default: tailwindcss } = await import('eleventy-plugin-tailwindcss-4');
  eleventyConfig.addPlugin(tailwindcss, {
    input: 'css/tailwind.css' // required
  });
};

Basic example

Generate output CSS at _site/styles.css from your input at src/css/tailwind.css

import tailwindcss from 'eleventy-plugin-tailwindcss-4'

export default (eleventyConfig) => {
  eleventyConfig.addPlugin(tailwindcss, {
    input: 'css/tailwind.css' 
  });
}

All options at default settings

Generate output CSS at _site/styles.css from your input at src/css/tailwind.css

import tailwindcss from 'eleventy-plugin-tailwindcss-4'

export default (eleventyConfig) => {
  eleventyConfig.addPlugin(tailwindcss, {
    input:'css/tailwind.css',
    output: 'styles.css',
    minify: false,
    watchOutput: true,
    watchImports: true,
    domDiff: true,
    sourceMap: false,
    debug: false
  });
}

CJS example

Generate minified CSS output at _site/css/main.css

module.exports = async function (eleventyConfig) {
  const { default: tailwindcss } = await import('eleventy-plugin-tailwindcss-4');

  eleventyConfig.addPlugin(tailwindcss, {
    input: 'css/tailwind.css', 
    output: 'css/main.css', 
    minify: true
  });
};

Link to the generated CSS

By defaul the plugin writes out your CSS to _site/styles.css or whatever you have named your output folder. Ensure you have link to the generated style sheet in the <head> of your template.

<link rel="stylesheet" href="/styles.css">

Options

Watching `@import`ed CSS files

The plugin automatically discovers CSS files referenced by @import statements in your source file and registers them as Eleventy watch targets. This means changes to imported files will trigger a rebuild when using --serve.

Nested imports are followed recursively. Set watchImports: false to disable this behaviour.

Enable debug: true to see which files are being watched and which are skipped.

Source maps

Set sourceMap: true to generate an external .map file alongside your CSS output, or sourceMap: 'inline' to embed the sourcemap directly in the CSS. Defaults to false (no sourcemap). See #2.

Output file naming

It is a good idea to not use the same name for your input and output file.

Using different names makes it easier to differentiate between the two files and know that processing has occured.
It avoids the output being overwitten if your source file is in a folder that you passThroughFileCopy to your output.

Example repo

Example repo of the plugin installed, configured (ES6) and working.

domDiff

The Dev Server's domDiffing is enabled by default. If you experience a flash of unstyled content, you can disable it with domDiff: false in the options.

Versions

3.0.0 ESM-only export. Watches @imported CSS files for changes (#4). Correctly respects the configured output directory (#5). Optional sourcemap generation (#2). Fixed issues with unstyled flashes.

2.0.1 Fixes an issue where in some cases output CSS could be written before output folder was created.

2.0.0 Major rewrite to use PostCSS under the hood

Thanks

@Hidden on the 11ty Discord