Color scheme

Lightning CSS Setup

In the Build Tooling reading you learned why CSS build tools exist and how Lightning CSS works as a single, all-in-one compiler. This page is the hands-on follow-up. You will install Lightning CSS, run a build command that bundles, prefixes, and minifies your CSS in one pass, and verify the output.

If you have limited experience with Node.js or the command line, do not worry. This page walks through every step. One of the advantages of Lightning CSS is how little setup it requires compared to plugin-based tools. 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/lightning-css-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/lightning-css-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

Lightning CSS is distributed as an npm package, so you need Node.js installed. If you already have Node 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. After installing, close and reopen your terminal, then verify with node --version again.

Initializing the Project

Navigate to your unit-2/lightning-css-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. If you prefer pnpm and already have it installed, you can use pnpm init instead.

Add a .gitignore File

Before you install anything, create a .gitignore file in your unit-2/lightning-css-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 Lightning CSS

You need two packages: Lightning CSS itself, and a file watcher for automatic rebuilds during development:


        npm install --save-dev lightningcss-cli chokidar-cli
    

If you are using pnpm, replace npm install with pnpm add. The --save-dev flag marks this as a development dependency, meaning it is a tool you use during development but do not ship to users.

That is the entire install. Unlike PostCSS, which relies on a pipeline of separate plugins, Lightning CSS handles bundling, vendor prefixing, minification, and syntax lowering all in one package. There is no config file to create and no plugins to choose between. Everything is controlled by command-line flags.

Adding a Build Script

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


        "scripts": {
            "build": "lightningcss --bundle --minify --targets \">= 0.25%\" css/main.css -o dist/styles.css",
            "watch": "chokidar \"css/**/*.css\" -c \"npm run build\" --debounce 600"
        }
    

This single command does everything. Here is what each flag does:

  • --bundle: resolves all @import statements and inlines the imported files into one output. This is the bundling step.
  • --minify: strips whitespace, shortens values, merges compatible rules, and removes comments. This is the minification step.
  • --targets ">= 0.25%": tells Lightning CSS which browsers to support. It will automatically add vendor prefixes where needed and, when possible, lower modern CSS syntax into equivalent older syntax for those browsers. The >= 0.25% value means "any browser with at least 0.25% global usage," which is a reasonable default.
  • -o dist/styles.css: the output file. 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 look at it. 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. One file, one command, done.

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.

Understanding What the Flags Did

To see each feature's contribution, try removing flags one at a time and rebuilding.

Without --minify

Remove the --minify flag, 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 useful for debugging because you can read the output and trace it back to your source files.

Without --bundle

Remove the --bundle flag (keep --minify), rebuild, and look at the output. You will see that dist/styles.css contains only the minified contents of main.css itself, with the @import statements still present. The browser would still need to fetch each file individually, which defeats the purpose.

Without --targets

Remove the --targets flag, rebuild, and compare. Without browser targets, Lightning CSS skips vendor prefixing and syntax lowering entirely. Your modern CSS ships as-is, which is fine for cutting-edge browsers but may cause issues in slightly older ones.

Restore all three flags when you are done experimenting.

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. Running npm run build manually after every change would be tedious, so you need a watch script that rebuilds automatically whenever you save a file.

Lightning CSS does not have a built-in watch mode, but a lightweight tool called chokidar-cli fills the gap. It watches your files and reruns a command when something changes. Install it as a dev dependency:


        npm install --save-dev chokidar-cli
    

Then add a watch script to your package.json alongside your build script:


        "scripts": {
            "build": "lightningcss --bundle --minify --targets \">= 0.25%\" css/main.css -o dist/styles.css",
            "watch": "chokidar \"css/**/*.css\" -c \"npm run build\" --debounce 600"
        }
    

Run npm run watch and leave it running in your terminal. Every time you save a CSS file anywhere inside the css/ directory, chokidar waits 600 milliseconds (to avoid rebuilding multiple times if you save several files in quick succession), then runs your build script. Press Ctrl+C to stop watching.

This is the watch workflow for the demo, and for a portfolio only if you keep using a bundler: start npm run watch when you sit down to work, edit your source files in css/, and refresh the browser to see your changes. The bundled output in dist/ stays up to date automatically.

Using npx Without a Local Install

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


        npx lightningcss-cli --bundle --minify --targets ">= 0.25%" css/main.css -o dist/styles.css
    

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

Comparing Lightning CSS to PostCSS

If your teammates chose the PostCSS path, compare notes. The same starter files produce the same result, but the setup is different:

  • PostCSS required three separate plugin packages plus a config file. Each plugin handled one job (bundling, prefixing, minification), and the order in the config mattered.
  • Lightning CSS required two packages (the CLI and a file watcher) and zero config files. Bundling, prefixing, minification, and syntax lowering are all built in and controlled by flags.

Neither approach is objectively better. PostCSS gives you more control and a larger plugin ecosystem. Lightning CSS gives you speed and simplicity. Both produce a single, optimized stylesheet from the same source architecture.

To see how Lightning CSS transforms modern CSS features, try the Lightning CSS Playground. Paste in some CSS with nesting, oklch() colors, or modern selectors, set a browser target, and see what comes out.

Your Final File Structure

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


        [unit-2/lightning-css-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
    

Notice there is no config file. That is one fewer file to maintain compared to PostCSS. The file watcher (chokidar-cli) is configured entirely in the package.json scripts. Remember to add a link to this page from your portfolio homepage and update your README.md.

Resources

Teaching Video Checklist

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

  • What Lightning CSS is and how it differs from plugin-based tools like PostCSS (one tool does everything, no config file, no plugins to install)
  • A live walkthrough of the setup: npm init, installing the package, adding the build script, and running it
  • What each CLI flag does (--bundle, --minify, --targets), ideally shown by removing 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 development workflow: using npm run watch so changes rebuild automatically, and when to use npm run build for a one-off production build
  • The importance of .gitignore for keeping node_modules/ out of the repository