How to Use Tailwind v4 with wp-scripts in WordPress Gutenberg

[bi1101]

I am trying to integrate Tailwind v4 with the wp-scripts package in a Plugin setting page.

Steps Taken:

• Followed the official TailwindCSS installation guide for PostCSS.
• Configured postcss.config.js based on Tailwind's recommendations.
• Ensured package.json scripts are using wp-scripts commands like build and start.

  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start --webpack-devtool --host example.local --hot",
    "format": "wp-scripts format ./src",
    "lint:js": "wp-scripts lint-js ./src"
  },

• Successfully register and enqueued the built js & css

However, when I use tailwind classes in my index.tsx, no style was applied

const SettingsPage = () => {
	return <h1 className="text-3xl font-bold text-red-900">Hello world!</h1>;
};

Questions:

1. Has anyone successfully integrated Tailwind v4 with wp-scripts in a Gutenberg project?
2. Are there specific configurations or scripts required for this setup?
3. Any common pitfalls or troubleshooting tips?

Any help or pointers would be greatly appreciated!

[RichForever]

Do you have @import "tailwindcss"; rule in you css file?

[bi1101]

Yes, I set up tailwind v3 and everything works well.

I installed v4 and some classes work but most don't.

I tried installing v3 and upgrading to v4 but no luck.

Fresh v4 install has same result.

I'm using wp-scripts postcss.

[itsseanl]

This probably isn't exactly what you're looking for, but I managed to integrate tailwindcss V4 into a custom block, and set up a repo describing how I did it here

[RichForever]

@itsseanl awesome work, thanks for sharing. You can simplify your webpack.config.file to this shape

const defaultConfig = require("@wordpress/scripts/config/webpack.config");

// Extract the existing PostCSS loader
const postCSSLoader = defaultConfig.module.rules
	.find((rule) => rule.test && rule.test.toString().includes("css"))
	.use.find((use) => use.loader && use.loader.includes("postcss-loader"));

// Add Tailwind to the PostCSS plugins
postCSSLoader.options.postcssOptions.plugins = [
	require("autoprefixer")({ grid: true }),
	require("@tailwindcss/postcss"),
	...(postCSSLoader.options.postcssOptions.plugins || []).filter(
		(plugin) => plugin !== "autoprefixer", // Avoid duplicate autoprefixer
	),
];

module.exports = defaultConfig;

Also, fix typos in path for edit.js in css files.
I can confirm that it's working, even with @apply rules

[itsseanl]

@RichForever you're welcome! Thanks for the tip on the webpack config, I'll try that out. I'm still kind of a noob with webpack 😄

[webowski]

@RichForever I tried the same webpack config modification. And when I run the npm start the webpack goes crazy and endlessly rebuilds every 50ms. Have you had this problem?

[krazew0rld]

hi @webowski Did you find a solution about problem on npm start ?

[tennessine]

that's awesome , but it's too complex to me.

[merijnponzo]

@tennessine

I got a workaround because i dont have time to dive into the rabithole of wp-scripts,

i Created a block
https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/

and use these steps:
https://tailwindcss.com/docs/installation/using-postcss

Make sure sure you installed postcss as well

npm i postcss postcss-cli

Create a eg style-tailwind.css inside your src block folder,

Then in package.json i added a build:css script

"build:css": "postcss src/visual3d/style-tailwind.css -o src/visual3d/style.scss",
"build": "npm run build:css && wp-scripts build --blocks-manifest",
"format": "wp-scripts format",
"lint:css": "wp-scripts lint-style",
"lint:js": "wp-scripts lint-js",
"packages-update": "wp-scripts packages-update",
"plugin-zip": "wp-scripts plugin-zip",
"start": "npm run build:css && wp-scripts start --blocks-manifest"

Its a bit of a lame fix but it works, so my block is called visual3d and has tailwind classes inside my jsx / tsx files and inside the style.css

whenever i use npm run build postcss is building first, then wordpress is using the generated style.scss

So to be clear, with this strategy you cant use the .scss file, but you will use your components and the style-tailwind.css (or whatever you want to call it)

[ejaz-ul-haq]

@bi1101

I have integrated Tailwind CSS v4 into the latest WordPress Scripts package build processing, and it is working perfectly with the default watch and build commands.
I have just followed the Tailwind CSS v4 documentation
https://tailwindcss.com/docs/installation/using-postcss

Note:
I have not installed the postcss package because it is already installed in the WordPress scripts bundle.
npm install tailwindcss @tailwindcss/postcss

Plugin Structure:

• assets
  -- gutenberg
  -- tailwind-css
• node-dev
  -- src
  --- package.json
  --- webpack.config.js
  --- gutenberg
  ---- blocks
  ---- sidebar
  --- tailwind-css
  ---- gutenberg-tailwind.css

The source code of the package.json file is following

{
	"name": "custom-plugin",
	"version": "1.0.0",
	"description": "This is a custom blocks plugin",
	"scripts": {
		"build": "wp-scripts build",
		"check-engines": "wp-scripts check-engines",
		"check-licenses": "wp-scripts check-licenses",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"lint:md:docs": "wp-scripts lint-md-docs",
		"lint:pkg-json": "wp-scripts lint-pkg-json",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start",
		"test:e2e": "wp-scripts test-e2e",
		"test:unit": "wp-scripts test-unit-js"
	},
	"author": "",
	"license": "ISC",
	"devDependencies": {
		"@wordpress/scripts": "^30.12.0",
		"cross-env": "^7.0.3"
	},
	"dependencies": {
		"@tailwindcss/postcss": "^4.1.8",
		"tailwindcss": "^4.1.8"
	}
} 

The source code of webpack.config.js file is following.

var path = require( 'path' );

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

/**
 * Inject @tailwindcss/postcss (Tailwind v4 bridge) into the default
 * @wordpress/scripts PostCSS chain *without* touching anything else.
 *
 * @param {Array<import('webpack').RuleSetRule>} rules
 * @return {Array<import('webpack').RuleSetRule>}
 */
const addTailwindToPostCSS = ( rules = [] ) => {
	const tailwindPlugin = require( '@tailwindcss/postcss' );

	return rules.map( ( rule ) => {
		if ( Array.isArray( rule.use ) ) {
			rule.use = rule.use.map( ( loader ) => {
				if (
					loader &&
					typeof loader === 'object' &&
					loader.loader?.includes( 'postcss-loader' )
				) {
					const opts         = loader.options || {};
					const postcssOpts  = opts.postcssOptions || {};

					postcssOpts.plugins = [
						...( postcssOpts.plugins || [] ), // keep WP defaults
						tailwindPlugin,                   // add Tailwind v4
					];

					loader.options = {
						...opts,
						postcssOptions: postcssOpts,
					};
				}
				return loader;
			} );
		}
		return rule;
	} );
};

/**
 * TailwindCSS v4 SUpport is added by addin it's PostCSS plugin (tailwindcss/postcss) in the default config postcss-loader plugins list 
 */
defaultConfig.module.rules = addTailwindToPostCSS( [ ...defaultConfig.module.rules ] );

/**
 * Added '.css' extension to handle the tailwindcss entry points in each config
 */
defaultConfig.resolve.extensions = [...defaultConfig.resolve.extensions, '.css'];

// If the default entry is a function, execute it to get the actual entry object
let defaultEntries = {};
if ( typeof defaultConfig.entry === 'function' ) {
	defaultEntries = defaultConfig.entry();
} else {
	defaultEntries = defaultConfig.entry;
}


var gutenbergConfig = Object.assign(
	{},
	{ ...defaultConfig },
	{
		name: 'gutenbergConfig',
		...{
			mode: NODE_ENV,
			entry: {
				...defaultEntries,
				// tailwind css entry point for a combine single tailwind generation for gutenberg
				'tailwind-css/gutenberg-tailwind': path.resolve(
					__dirname,
					'./src/tailwind-css/gutenberg-tailwind.css'
				),
			},
			output: {
				filename: '[name].js',
				path: path.resolve( __dirname, '../assets/' ),
			},
			plugins: plugins,
		},
	}
);

/**
 * Export Final Configs
 */
module.exports = [gutenbergConfig];

The source code of the gutenberg-tailwind.css file is following.

@import "tailwindcss";

[ejaz-ul-haq]

I have created a custom plugin that utilizes the WordPress scripts with Tailwind CSS v4 and Ant-Design inside blocks and backend-panel and frontend-panel.
I hope the following structure will be very helpful for those who want to have a similar solution and implementation.

Plugin Structure:

assets
-- backend
-- frontend
-- gutenberg
-- tailwind-css
node-dev
-- src
--- package.json
--- webpack.config.js
--- backend
---- app.jsx
---- images
--- frontend
---- app.jsx
---- images
--- gutenberg
---- blocks
---- sidebar
--- tailwind-css
---- backend-tailwind.css
---- frontend-tailwind.css
---- gutenberg-tailwind.css

The source code of the package.json file is following

{
	"name": "wpinnovators-customizations",
	"version": "1.0.0",
	"description": "This is custom blocks plugin",
	"scripts": {
		"build": "wp-scripts build",
		"check-engines": "wp-scripts check-engines",
		"check-licenses": "wp-scripts check-licenses",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"lint:md:docs": "wp-scripts lint-md-docs",
		"lint:pkg-json": "wp-scripts lint-pkg-json",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start",
		"test:e2e": "wp-scripts test-e2e",
		"test:unit": "wp-scripts test-unit-js",
		"build:gutenberg": "cross-env BUILD_TYPE=gutenberg wp-scripts build --webpack-src-dir=src/gutenberg/ --output-path=../assets/gutenberg/",
		"build:frontend": "cross-env BUILD_TYPE=frontend wp-scripts build",
		"build:backend": "cross-env BUILD_TYPE=backend wp-scripts build"
	},
	"author": "",
	"license": "ISC",
	"devDependencies": {
		"@wordpress/scripts": "^30.12.0",
		"cross-env": "^7.0.3",
		"filemanager-webpack-plugin": "^8.0.0"
	},
	"dependencies": {
		"@ant-design/pro-components": "^2.8.6",
		"@emotion/css": "^11.13.5",
		"@paddle/paddle-js": "^1.3.3",
		"@tailwindcss/postcss": "^4.1.8",
		"antd": "^5.24.2",
		"tailwindcss": "^4.1.8"
	}
}

The source code of webpack.config.js file is following.

var path = require( 'path' );
const NODE_ENV = process.env.NODE_ENV || 'development';
const FileManagerPlugin = require( 'filemanager-webpack-plugin' );
const create_zip = process.env.CREATE_ZIP || 'no'; // Change this to 'yes' to create the zip
const build_type = process.env.BUILD_TYPE || 'all'; // Change this to 'gutenberg' to create gutenberg blocks etc build

/**
 * WordPress Dependencies
 */
const defaultConfig = require( '@wordpress/scripts/config/webpack.config.js' );

// Base plugins array from default config
const plugins = [ ...defaultConfig.plugins ];


/**
 * Inject @tailwindcss/postcss (Tailwind v4 bridge) into the default
 * @wordpress/scripts PostCSS chain *without* touching anything else.
 *
 * @param {Array<import('webpack').RuleSetRule>} rules
 * @return {Array<import('webpack').RuleSetRule>}
 */
const addTailwindToPostCSS = ( rules = [] ) => {
	const tailwindPlugin = require( '@tailwindcss/postcss' );

	return rules.map( ( rule ) => {
		if ( Array.isArray( rule.use ) ) {
			rule.use = rule.use.map( ( loader ) => {
				if (
					loader &&
					typeof loader === 'object' &&
					loader.loader?.includes( 'postcss-loader' )
				) {
					const opts         = loader.options || {};
					const postcssOpts  = opts.postcssOptions || {};

					postcssOpts.plugins = [
						...( postcssOpts.plugins || [] ), // keep WP defaults
						tailwindPlugin,                   // add Tailwind v4
					];

					loader.options = {
						...opts,
						postcssOptions: postcssOpts,
					};
				}
				return loader;
			} );
		}
		return rule;
	} );
};

/**
 * TailwindCSS v4 SUpport is added by addin it's PostCSS plugin (tailwindcss/postcss) in the default config postcss-loader plugins list 
 */
defaultConfig.module.rules = addTailwindToPostCSS( [ ...defaultConfig.module.rules ] );

/**
 * Added '.css' extension to handle the tailwindcss entry points in each config
 */
defaultConfig.resolve.extensions = [...defaultConfig.resolve.extensions, '.css'];


var backendConfig = Object.assign(
	{},
	{ ...defaultConfig },
	{
		name: 'backendConfig',
		...{
			mode: NODE_ENV,
			entry: {
				'backend/app': path.resolve(
					__dirname, 
					'./src/backend/app.jsx',
				),
				// tailwind css entry point for a combine single tailwind generation for backend
				'tailwind-css/backend-tailwind': path.resolve(
					__dirname,
					'./src/tailwind-css/backend-tailwind.css'
				),
			},
			output: {
				filename: '[name].js',
				path: path.resolve( __dirname, '../assets/' ),
			},
			plugins: plugins.map(plugin => {
				if (plugin.constructor.name === 'CopyPlugin') {
				  return new CopyPlugin({
					patterns: [
						{
							from: path.resolve(__dirname, 'src/backend/images'),
							to: path.resolve(__dirname, '../assets/backend/images'),
							noErrorOnMissing: true
						}
					]
				  });
				}
				return plugin;
			}),
		},
	}
);

var frontendConfig = Object.assign(
	{},
	{ ...defaultConfig },
	{
		name: 'frontendConfig',
		...{
			mode: NODE_ENV,
			entry: {
				'frontend/app': path.resolve(
					__dirname, 
					'./src/frontend/app.jsx',
				),
				// tailwind css entry point for a combine single tailwind generation for frontend
				'tailwind-css/frontend-tailwind': path.resolve(
					__dirname,
					'./src/tailwind-css/frontend-tailwind.css'
				),
			},
			output: {
				filename: '[name].js',
				path: path.resolve( __dirname, '../assets/' ),
			},
			plugins: plugins.map(plugin => {
				if (plugin.constructor.name === 'CopyPlugin') {
				  return new CopyPlugin({
					patterns: [
						{
							from: path.resolve(__dirname, 'src/frontend/images'),
							to: path.resolve(__dirname, '../assets/frontend/images'),
							noErrorOnMissing: true
						}
					]
				  });
				}
				return plugin;
			}),
		},
	}
);

// If the default entry is a function, execute it to get the actual entry object
let defaultEntries = {};
if ( typeof defaultConfig.entry === 'function' ) {
	defaultEntries = defaultConfig.entry();
} else {
	defaultEntries = defaultConfig.entry;
}

// console.log('defaultEntries - before');
// console.log(JSON.stringify(defaultEntries));

var gutenbergConfig = Object.assign(
	{},
	{ ...defaultConfig },
	{
		name: 'gutenbergConfig',
		...{
			mode: NODE_ENV,
			entry: {
				...defaultEntries,
				// tailwind css entry point for a combine single tailwind generation for gutenberg
				'tailwind-css/gutenberg-tailwind': path.resolve(
					__dirname,
					'./src/tailwind-css/gutenberg-tailwind.css'
				),
			},
			output: {
				filename: '[name].js',
				path: path.resolve( __dirname, '../assets/' ),
			},
			plugins: plugins,
		},
	}
);


const configs = {
	gutenberg: [ gutenbergConfig ],
	backend: [ backendConfig ],
	frontend: [ frontendConfig ],
	all: [ backendConfig, frontendConfig, gutenbergConfig ], // Default case
};

const selectedConfig = configs[ build_type ] || configs.all;


/**
 * Export Final Configs
 */
module.exports = selectedConfig;

[snorkellingcactus]

It just worked for me. Followed the tailwind postcss install guide.

Just had to add source on tailwind import to prevent a build infinite loop:

src/my_block/style.scss

@import "tailwindcss" source("./*.js");

postcss.config.js

module.exports = {
  plugins: [
    require('@tailwindcss/postcss')
  ],
};

No webpack.config.js

        "scripts": {
		"build": "wp-scripts build --blocks-manifest",
		"format": "wp-scripts format",
		"lint:css": "wp-scripts lint-style",
		"lint:js": "wp-scripts lint-js",
		"packages-update": "wp-scripts packages-update",
		"plugin-zip": "wp-scripts plugin-zip",
		"start": "wp-scripts start --blocks-manifest"
	},
	"devDependencies": {
		"@tailwindcss/postcss": "^4.1.13",
		"@wordpress/scripts": "^30.24.0",
		"autoprefixer": "^10.4.21",
		"postcss": "^8.5.6",
		"sass": "^1.93.2",
		"tailwindcss": "^4.1.13"
	}

(i think i dont needed to add autoprefixer, and not sure if it's actually necessary to explicitly install postcss or sass)

[RichForever]

What about compiled css? Does every block contain base tailwind styles or only styles for classes that are in js files?

[snorkellingcactus]

Layer base and layer theme has some css (just a bit and the later is like reset style css)

And layer utilites has only the css i used on the JS files

[KevinBatdorf]

Here's an esm version of the solution:

// webpack.config.js
import tailwindcss from "@tailwindcss/postcss";
import defaultConfig from "@wordpress/scripts/config/webpack.config.js";

// Override PostCSS configuration
const loader = defaultConfig.module.rules
	.find(({ test }) => test?.toString()?.includes("css"))
	.use.find(({ loader }) => loader?.includes("postcss-loader"));
loader.options.postcssOptions.plugins = [tailwindcss()];

export default defaultConfig;

Make sure you don't also have a postcss config file in the directory

[Vince-ALIEN]

The best way i find to build Tailwind ccs Gutemberg blocks : https://github.com/Vince-ALIEN/ufo-blocks
You can see results at : https://www.ufo-agency.com/

To use my blocks with your Tailwind WordPress theme just add : @source "../../../plugins/ufo-blocks/src/**/*.js";

Before your : @theme

Then npm run watch, build, etc...

Best regards