Color scheme

PostCSS Setup and Plugins

In the Build Tooling reading you learned why CSS build tools exist and how PostCSS works as a plugin pipeline. This page is the hands-on follow-up. You will install PostCSS, configure three plugins, and run a build that turns your multi-file CSS architecture into a single, minified, production-ready stylesheet.

If you have limited experience with Node.js or the command line, do not worry. This page walks through every step. You will use this setup in the Architecture and Build assignment. After that week a bundler is optional on your portfolio. See After This Assignment: Stop or Keep.

Setup

Download the CSS Bundling starter files and extract them into your portfolio at unit-2/postcss-demo/. The zip contains an index.html page and a css/ directory with the layered architecture you learned in the CSS Architecture reading. All the CSS is already written and working. Your job is not to write CSS on this page. It is to set up a build tool that bundles it.

Open the page in your browser to confirm it looks correct before you change anything. You should see a temple comparison page with two cards, images, and a short reflection section. This is your baseline. After the build process is set up, the page should look exactly the same but load from a single bundled file instead of many separate ones.


        [unit-2/postcss-demo]
        ├── css/
        │   ├── base/
        │   │   ├── elements.css
        │   │   └── reset.css
        │   ├── components/
        │   │   └── card.css
        │   ├── layout/
        │   │   ├── chrome.css
        │   │   └── primary.css
        │   ├── tokens/
        │   │   ├── colors.css
        │   │   └── variables.css
        │   ├── utilities/
        │   │   └── utilities.css
        │   └── main.css
        └── index.html
    

Installing Node.js

PostCSS runs on Node.js. If you already have Node installed from a previous course or project, you can skip this section. To check, open your terminal and run:


        node --version
    

If you see a version number (like v20.x.x or higher), you are good to go. If the command is not recognized, download and install the LTS (Long Term Support) version from nodejs.org. The LTS version is the stable, recommended release. After installing, close and reopen your terminal, then verify with node --version again.

Initializing the Project

Navigate to your unit-2/postcss-demo/ directory in the terminal. You need to create a package.json file, which is how Node.js tracks your project's dependencies and scripts. Run:


        npm init -y
    

The -y flag accepts all the defaults so you do not have to answer a series of questions. This creates a package.json file in your project directory. If you prefer pnpm and already have it installed, you can use pnpm init instead. Both work the same way for this project.

Add a .gitignore File

Before you install anything, create a .gitignore file in your unit-2/postcss-demo/ directory with the following content:


        node_modules/
    

The node_modules/ directory is where Node stores installed packages. It can contain thousands of files and should never be committed to your repository. The .gitignore file tells Git to skip it. If you already have a .gitignore at your portfolio root that includes node_modules/, you are covered, but adding one here as well is a safe habit.

Installing PostCSS and Plugins

You need three packages: PostCSS itself, its command-line interface, and three plugins. Install them all at once:


        npm install --save-dev postcss postcss-cli postcss-import autoprefixer cssnano
    

If you are using pnpm, replace npm install with pnpm add. The --save-dev flag marks these as development dependencies, meaning they are tools you use during development but do not ship to users.

Here is what each package does:

  • postcss: the core framework that parses your CSS and passes it through plugins.
  • postcss-cli: a command-line tool that lets you run PostCSS from the terminal without writing JavaScript.
  • postcss-import: resolves @import statements and inlines every imported file into one output. This is the bundling step.
  • autoprefixer: reads your browser targets and automatically adds vendor prefixes where needed.
  • cssnano: minifies the output by removing whitespace, shortening values, and stripping comments.

Creating the PostCSS Config

PostCSS looks for a configuration file that tells it which plugins to use and in what order. Create a file called postcss.config.js in your unit-2/postcss-demo/ directory:


        module.exports = {
            plugins: [
                require('postcss-import'),
                require('autoprefixer'),
                require('cssnano')({ preset: 'default' })
            ]
        };
    

The order matters. postcss-import must come first because the other plugins need to work on a single, fully resolved stylesheet. If autoprefixer or cssnano ran before the imports were resolved, they would only process main.css itself and miss everything it imports.

Adding a Build Script

Open your package.json and find the "scripts" section. Replace the default "test" script with a build command:


        "scripts": {
            "build": "postcss css/main.css --output dist/styles.css"
        }
    

This tells PostCSS to read css/main.css as the entry point, run it through your configured plugins, and write the result to dist/styles.css. The dist/ directory will be created automatically.

Now run the build:


        npm run build
    

If everything is set up correctly, you will see a new dist/ directory containing styles.css. Open that file and compare it to your source files. You should see that all of the @import statements are gone, the content of every file has been inlined, vendor prefixes have been added where needed, and all whitespace and comments have been stripped.

Switching to the Bundled File

Your index.html currently links to css/main.css, which triggers all those individual @import requests. Update the stylesheet link to point to the bundled output instead:


        <!-- Before: multi-file with @import -->
        <link rel="stylesheet" href="css/main.css">

        <!-- After: single bundled file -->
        <link rel="stylesheet" href="dist/styles.css">
    

Refresh the page in your browser. It should look exactly the same, but now open DevTools and check the Network tab. Instead of separate requests for every CSS file, you should see a single request for styles.css. That is the entire point of this demo.

Switch this demo page to dist/styles.css so you can see one Network request. On your portfolio the default live sheet stays css/main.css unless you keep using a bundler. See After This Assignment: Stop or Keep.

The Development Workflow

You now have two versions of your CSS: the source files in css/ that you edit, and the bundled output in dist/ that this demo page loads. When you make changes to any source file, you need to run npm run build again to regenerate the bundle.

For convenience, you can add a watch script that rebuilds automatically whenever a source file changes. Update your package.json scripts:


        "scripts": {
            "build": "postcss css/main.css --output dist/styles.css",
            "watch": "postcss css/main.css --output dist/styles.css --watch"
        }
    

Run npm run watch and PostCSS will stay running in the background, rebuilding dist/styles.css every time you save a change. Press Ctrl+C in the terminal to stop watching.

Understanding What Each Plugin Did

To see each plugin's contribution, try disabling them one at a time in your config and rebuilding.

Without cssnano

Comment out the cssnano line, rebuild, and open dist/styles.css. You will see all your CSS bundled and prefixed, but with full whitespace, comments, and readable formatting intact. This is what your bundled output looks like before minification.

Without autoprefixer

Comment out the autoprefixer line, rebuild, and compare. Depending on your CSS, you may notice missing -webkit- prefixes for properties like backdrop-filter or clip-path that some older browsers still need.

Without postcss-import

Comment out postcss-import, rebuild, and look at the output. You will see that dist/styles.css contains only the layer declaration and the @import statements from main.css, not the actual content of the imported files. The browser would still need to fetch each file individually, which defeats the purpose of bundling.

Re-enable all three plugins when you are done experimenting.

Using npx Without a Global Install

Everything above uses npm run build, which runs PostCSS through your project's local install. If you ever want to run PostCSS without creating a package.json or installing anything locally, you can use npx to run it as a one-off command:


        npx postcss css/main.css --output dist/styles.css --use postcss-import autoprefixer cssnano
    

This downloads and runs everything temporarily. It is useful for quick experiments but not recommended for a real project. For anything you will revisit, the package.json and config file approach is more reliable and reproducible.

Your Final File Structure

After completing all the steps, your project directory should look like this:


        [unit-2/postcss-demo]
        ├── css/
        │   ├── base/
        │   │   ├── elements.css
        │   │   └── reset.css
        │   ├── components/
        │   │   └── card.css
        │   ├── layout/
        │   │   ├── chrome.css
        │   │   └── primary.css
        │   ├── tokens/
        │   │   ├── colors.css
        │   │   └── variables.css
        │   ├── utilities/
        │   │   └── utilities.css
        │   └── main.css
        ├── dist/
        │   └── styles.css
        ├── node_modules/
        ├── .gitignore
        ├── index.html
        ├── package.json
        └── postcss.config.js
    

Remember to add a link to this page from your portfolio homepage and update your README.md.

Going Further

The three plugins you installed cover the most common needs: bundling, prefixing, and minification. PostCSS has a large ecosystem of community plugins if you want to explore further. Two worth knowing about:

  • postcss-preset-env lets you use future CSS syntax (like custom media queries or range media queries) and compiles it down to compatible output based on your browser targets. You can try it in the PostCSS Preset Env Playground.
  • postcss-custom-media polyfills the @custom-media specification, letting you define reusable media query conditions. Your teammate who picked the @custom-media choose topic will cover this in depth.

These are optional. The three-plugin setup you have now is a solid, production-ready pipeline.

Resources

Teaching Video Checklist

Your teammates should come away from your video understanding these concepts:

  • What PostCSS is and how its plugin pipeline works (CSS goes in, plugins transform it, production CSS comes out)
  • A live walkthrough of the setup: npm init, installing packages, creating the config file, and running the build
  • What each of the three plugins does, ideally shown by disabling one at a time and comparing the output
  • The difference between the source files in css/ and the bundled output in dist/, and why this demo page switches to the bundled file. The portfolio default after Architecture and Build is still css/main.css unless you keep using a bundler.
  • The importance of .gitignore for keeping node_modules/ out of the repository