How to use Tailwind 4 in a SPFx webpart with Rushstack and Heft?

[derLesh]

Hello,

I am currently trying out version 1.22 of SharePoint Framework (SPFx), where Gulp has been replaced by Heft.

This has changed the method I use to add TailwindCSS, and that's where I'm having problems.
With Gulp, I always used TailwindCSS 3 and installed the following dependencies: npm i autoprefixer gulp-postcss postcss [email protected] esbuild-loader

The CSS file was stored under /src/webparts/ProjectName/assets/

However, in order to integrate Tailwind into the build process, I had to add the following to gulpfile.js:

const postcss = require('gulp-postcss');
const tailwind = require('tailwindcss');

const tailwindcss = build.subTask('tailwindcss', function (gulp, buildOptions, done) {
const webpartPath = 'ProjectName';

gulp
   .src(`src/webparts/${webpartPath}/assets/tailwind.css`)
   .pipe(postcss([tailwind('./tailwind.config.js')]))
   .pipe(gulp.dest('assets/dist'));
  done();
});
build.rig.addPreBuildTask(tailwindcss);

I am now trying to use TailwindCSS 4 with PostCSS in the SPFx webpart, but I am having problems importing the Tailwind CSS file.

I have installed the following dependencies: npm i autoprefixer postcss tailwindcss @tailwindcss/postcss esbuild-loader

postcss.config.mjs

export default {
  plugins: {
    “@tailwindcss/postcss”: {},
  }
}

tailwind.config,js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{html,js,tsx}"],
  theme: {
    extend: {
        
    },
  },
  plugins: [],
}

When I import the CSS file into the webpart, I get this error message:

ERROR in ./lib/webparts/ProjectName/styles/tailwind.css
Module build failed (from ./node_modules/@microsoft/sp-css-loader/lib-commonjs/index.js):
Error: Only the "url" import type is supported. Encountered "@import"
    at Object.processCssAsync (C:\Users\Lukas\Documents\Projekte\Sharepoint\ProjectName\node_modules\@microsoft\sp-css-loader\lib-commonjs\index.js:117:31)
 @ ./lib/webparts/ProjectName/ProjectNameWebPart.js 11:0-32

Has anyone gotten TailwindCSS to work with Heft or found any workaround?

[wongjn]

It seems like Heft doesn't have direct support for PostCSS but you may be able to use it (and by extension Tailwind) through Webpack.

---

As an aside:

• tailwind.config.js is not really used in v4.
• You don't need autoprefixer with v4.

[ayakhaled0001]

This is a common issue when migrating from Gulp-based SPFx builds to Heft. The problem is that @microsoft/sp-css-loader doesn't understand PostCSS syntax like @import and @tailwind directives.

Here are several solutions to get TailwindCSS working with SPFx + Heft:

Solution 1: Pre-compile Tailwind CSS (Recommended)
Create a separate build step to pre-compile your Tailwind CSS before the SPFx build runs.

1. Install dependencies:

npm i -D tailwindcss@latest postcss@latest autoprefixer@latest

2. Create a build script (build-tailwind.js):

const postcss = require('postcss');
const tailwindcss = require('tailwindcss');
const autoprefixer = require('autoprefixer');
const fs = require('fs').promises;
const path = require('path');

async function buildTailwind() {
  try {
    // Read your Tailwind CSS source
    const css = await fs.readFile('./src/webparts/yourProject/assets/tailwind.css', 'utf8');
    
    // Process with PostCSS + Tailwind
    const result = await postcss([
      tailwindcss('./tailwind.config.js'),
      autoprefixer
    ]).process(css, {
      from: './src/webparts/yourProject/assets/tailwind.css',
      to: './lib/webparts/yourProject/styles/tailwind.css'
    });
    
    // Ensure directory exists
    await fs.mkdir('./lib/webparts/yourProject/styles', { recursive: true });
    
    // Write the compiled CSS
    await fs.writeFile('./lib/webparts/yourProject/styles/tailwind.css', result.css);
    
    console.log('Tailwind CSS compiled successfully!');
  } catch (error) {
    console.error('Error compiling Tailwind CSS:', error);
    process.exit(1);
  }
}
buildTailwind();

3. Add to package.json scripts:

json

{
  "scripts": {
    "build": "npm run build:tailwind && heft build",
    "build:tailwind": "node build-tailwind.js",
    "dev": "npm run build:tailwind && heft dev",
    "tailwind:watch": "nodemon --watch src/webparts/**/assets/tailwind.css --watch tailwind.config.js --exec \"npm run build:tailwind\""
  }
}

4. Update your import:

In your webpart:

typescript
import './styles/tailwind.css';

[wongjn]

This would only work for v3 but OP is specifically asking for v4.

[derLesh]

Thank you for your answer.
It seems like your script refer to Tailwind 3, based on the use of autoprefixer and tailwind.config.js.
This causes the following error, when running the build script:

Error compiling Tailwind CSS: Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

I've created a postcss.config.mjs file in root and set @tailwindcss/postcss as a plugin. Also I replaced const tailwindcss = require('tailwindcss'); with const tailwindcss = require('@tailwindcss/postcss');. The script would run without any errors.

Instead of PostCSS I tried using TailwindCSS CLI. It seems like it is doing the same like your script, but with direct support for Tailwind 4.
Only annoying thing is that I have to additionally run Tailwind CLI with --watch, while running heft start --watch