A PostCSS plugin for transforming CSS if() functions into native CSS @media and @supports rules at build time.

This plugin is part of the css-if-polyfill project and provides build-time transformation of conditional CSS, eliminating the need for runtime JavaScript processing when using only media() and supports() functions.

Input CSS:

.responsive {
	width: if(media(width <= 768px): 100%; else: 50%);
}

Expected Output:

.responsive {
	width: 50%;
}
@media (width <= 768px) {
	.responsive {
		width: 100%;
	}
}

npm install postcss-if-function postcss

# Transform CSS using PostCSS CLI
npx postcss input.css --output output.css --use postcss-if-function

# With custom PostCSS config file
npx postcss input.css --output output.css --config postcss.config.js

import postcss from "postcss";
import postcssIfFunction from "postcss-if-function";

const css = `
.example {
  color: if(media(max-width: 768px): blue; else: red);
  font-size: if(supports(display: grid): 1.2rem; else: 1rem);
}
`;

const result = await postcss([postcssIfFunction()]).process(css, {
	from: undefined
});

console.log(result.css);

Output:

.example {
	color: red;
}
@media (max-width: 768px) {
	.example {
		color: blue;
	}
}
.example {
	font-size: 1rem;
}
@supports (display: grid) {
	.example {
		font-size: 1.2rem;
	}
}

const result = await postcss([
	postcssIfFunction({
		logTransformations: true,
		preserveOriginal: false,
		skipSelectors: [".no-transform"]
	})
]).process(css, { from: undefined });

// postcss.config.js
import postcssIfFunction from "postcss-if-function";

export default {
	plugins: [
		postcssIfFunction({
			logTransformations: process.env.NODE_ENV === "development"
		})
	]
};

// postcss.config.cjs (CommonJS)
module.exports = {
	plugins: [require("postcss-if-function")]
};

// vite.config.js
import { defineConfig } from "vite";
import postcssIfFunction from "postcss-if-function";

export default defineConfig({
	css: {
		postcss: {
			plugins: [
				postcssIfFunction({
					logTransformations: process.env.NODE_ENV === "development"
				})
			]
		}
	}
});

// webpack.config.js
module.exports = {
	module: {
		rules: [
			{
				test: /\.css$/,
				use: [
					"style-loader",
					"css-loader",
					{
						loader: "postcss-loader",
						options: {
							postcssOptions: {
								plugins: [
									[
										"postcss-if-function",
										{
											logTransformations: true
										}
									]
								]
							}
						}
					}
				]
			}
		]
	}
};

// next.config.js
module.exports = {
	experimental: {
		postcss: {
			plugins: {
				"postcss-if-function": {
					logTransformations: process.env.NODE_ENV === "development"
				}
			}
		}
	}
};

Input CSS:

.responsive {
	width: if(media(width <= 768px): 100%; else: 50%);
}

Expected Output:

.responsive {
	width: 50%;
}
@media (width <= 768px) {
	.responsive {
		width: 100%;
	}
}

Input CSS:

.grid {
	display: if(supports(display: grid): grid; else: block);
}

Expected Output:

.grid {
	display: block;
}
@supports (display: grid) {
	.grid {
		display: grid;
	}
}

Input CSS:

.responsive {
	padding: if(
		media(width >= 1200px): 40px; media(width >= 768px): 30px;
			media(width >= 480px): 20px; else: 15px
	);
}

Expected Output:

.responsive {
	padding: 15px;
}
@media (width >= 480px) {
	.responsive {
		padding: 20px;
	}
}
@media (width >= 768px) {
	.responsive {
		padding: 30px;
	}
}
@media (width >= 1200px) {
	.responsive {
		padding: 40px;
	}
}

• Style Functions Not Supported: This plugin only transforms media() and supports() functions. For style() functions (which depend on runtime DOM state), use the css-if-polyfill runtime (browser) library
• Static Analysis Only: The plugin performs static analysis and cannot handle dynamically generated CSS
• PostCSS Compatibility: Requires PostCSS 8.0.0 or higher

For complete CSS if() support including style() functions, combine this plugin with the runtime polyfill:

1. Use this PostCSS plugin for build-time transformation of media() and supports()
2. Use css-if-polyfill runtime for style() functions

<!-- For style() functions only -->
<script src="https://cdn.jsdelivr.net/npm/css-if-polyfill/dist/index.modern.js"></script>

This plugin is designed for optimal build-time performance, transforming CSS if() functions to native CSS without runtime overhead. However, there are some architectural considerations:

• Double Parsing: The plugin currently parses CSS twice - once by PostCSS and once by the transformation engine
• String-based Transformation: The transformation engine outputs CSS strings that are re-parsed into PostCSS AST nodes

• Reduced CSS Code: We'll make use of CSS Nesting capabilities as soon as any of the browsers are EOL (#35).
• Direct AST Transformation: The transformation engine could be modified to output PostCSS AST nodes directly, eliminating the double parsing overhead
• Streaming Processing: For very large CSS files, streaming transformation could reduce memory usage

For most typical usage scenarios, the current performance is excellent and the double parsing overhead is negligible compared to the benefits of build-time transformation.

See the main Contributing Guide for details on how to contribute to this project.

MIT © Maximilian Franzke

• PostCSS - Tool for transforming CSS with JavaScript
• CSS Conditional Rules - MDN documentation for @media and @supports

• css-if-polyfill - Runtime polyfill for CSS if() functions
• lightningcss-plugin-if-function - Lightning CSS plugin for build-time transformation
• stylelint-config-if-function - Stylelint configuration for linting CSS if() usage