PostCSS Website Markup

Website Markup with PostCSS

PostCSS is a tool for CSS transformation through JavaScript plugins. It does nothing by itself — all behavior is defined by plugins. Tailwind CSS runs on PostCSS. Autoprefixer is a PostCSS plugin. CSS Modules are processed by PostCSS. PostCSS is not a replacement for SCSS, but a transformation layer that can be used in combination with any preprocessor or standalone.

Installation and Basic Configuration

npm install -D postcss

// postcss.config.js
/** @type {import('postcss').Config} */
module.exports = {
  plugins: [
    require('postcss-import'),          // @import → inline
    require('postcss-nested'),          // Nesting like in SCSS
    require('postcss-custom-media'),    // Custom Media Queries
    require('autoprefixer'),            // Vendor prefixes
    require('postcss-preset-env')({     // Modern CSS → compatible
      stage: 2,
      features: {
        'nesting-rules': true,
        'custom-properties': false,     // Keep native
        'color-function': true,
      },
    }),
    ...(process.env.NODE_ENV === 'production'
      ? [require('cssnano')({ preset: 'default' })]
      : []),
  ],
};

PostCSS config in Vite is read automatically from the project root or via css.postcss in vite.config.ts.

Key Plugins

postcss-import

Replaces @import with file contents during the build — single CSS file without HTTP requests:

/* src/styles/main.css */
@import "./reset.css";
@import "./tokens.css";
@import "./base.css";
@import "./components/button.css";
@import "./components/card.css";
@import "./layout/header.css";
@import "./pages/home.css";

postcss-nested — nesting without SCSS

/* Before processing */
.card {
  background: var(--color-surface);
  border-radius: var(--radius-lg);

  &:hover {
    box-shadow: var(--shadow-md);
  }

  & .card-title {
    font-size: 1.25rem;
    font-weight: 600;
  }

  @media (min-width: 768px) {
    padding: 2rem;
  }
}

/* After processing */
.card { background: var(--color-surface); border-radius: var(--radius-lg); }
.card:hover { box-shadow: var(--shadow-md); }
.card .card-title { font-size: 1.25rem; font-weight: 600; }
@media (min-width: 768px) { .card { padding: 2rem; } }

postcss-custom-media

/* Define custom media queries once */
@custom-media --sm (min-width: 576px);
@custom-media --md (min-width: 768px);
@custom-media --lg (min-width: 1024px);
@custom-media --xl (min-width: 1280px);
@custom-media --dark (prefers-color-scheme: dark);
@custom-media --motion-ok (prefers-reduced-motion: no-preference);

/* Usage */
.hero {
  padding: 3rem 1rem;

  @media (--md) {
    padding: 6rem 2rem;
  }

  @media (--lg) {
    flex-direction: row;
    padding: 8rem 3rem;
  }
}

.card {
  @media (--dark) {
    background: #1e293b;
    color: #f1f5f9;
  }
}

.animated-element {
  @media (--motion-ok) {
    transition: transform 300ms ease;
  }
}

postcss-preset-env — native modern CSS

/* Native CSS nesting (Level 4) → PostCSS unfolds for old browsers */
.nav {
  display: flex;
  gap: 1rem;

  & a {
    color: var(--color-text-secondary);

    &:hover {
      color: var(--color-text-primary);
    }

    &[aria-current="page"] {
      color: var(--color-accent);
      font-weight: 500;
    }
  }
}

/* :is() and :where() */
:is(h1, h2, h3, h4) {
  font-weight: 600;
  line-height: 1.3;
}

/* color-mix() */
.button-hover {
  background: color-mix(in srgb, var(--color-accent) 85%, black);
}

/* oklch colors */
.primary {
  color: oklch(50% 0.2 264);
}

cssnano — minification

// Fine-tuning cssnano
require('cssnano')({
  preset: ['advanced', {
    discardComments: { removeAll: true },
    reduceIdents: false,      // Don't rename @keyframes
    zindex: false,            // Don't optimize z-index
    colormin: true,
    minifyFontValues: true,
  }],
})

Custom PostCSS Plugin

When standard plugins aren't enough:

// postcss-theme-tokens.js
const plugin = require('postcss').plugin('postcss-theme-tokens', (opts = {}) => {
  return (root) => {
    root.walkRules((rule) => {
      if (rule.selector === ':root') {
        rule.walkDecls(/^--/, (decl) => {
          // Log all tokens for documentation
          if (opts.log) {
            console.log(`Token: ${decl.prop} = ${decl.value}`);
          }
        });
      }
    });
  };
});

module.exports = plugin;

Or via modern API:

// postcss-strip-debug.mjs
export default {
  postcssPlugin: 'postcss-strip-debug',
  Declaration(decl) {
    // Remove border: 1px solid red; from production
    if (
      process.env.NODE_ENV === 'production' &&
      decl.prop === 'border' &&
      decl.value.includes('red')
    ) {
      decl.remove();
    }
  },
};
export const postcss = true;

PurgeCSS via PostCSS

npm install -D @fullhuman/postcss-purgecss

// postcss.config.js
module.exports = {
  plugins: [
    ...(process.env.NODE_ENV === 'production'
      ? [
          require('@fullhuman/postcss-purgecss')({
            content: ['./src/**/*.{html,jsx,tsx,vue}'],
            defaultExtractor: (content) =>
              content.match(/[\w-/:]+(?<!:)/g) || [],
            safelist: {
              standard: [/^is-/, /^has-/, /^data-/],
              greedy: [/modal/, /tooltip/],
            },
          }),
        ]
      : []),
  ],
};

Integration with SCSS

PostCSS and SCSS work sequentially — SCSS compiles first, PostCSS processes the result:

// vite.config.ts
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/styles/abstracts" as *;`,
      },
    },
    postcss: {
      plugins: [autoprefixer(), cssnano()],
    },
  },
});

Timeline

Setting up a chain of PostCSS plugins for a project: 2–4 hours. PostCSS is generally added to existing tooling, rather than used standalone. Writing a custom plugin for a specific task: 2–6 hours depending on the transformation complexity.