Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 38 ยท Assets and CSS

Sass, Less and PostCSS

Add Sass, Less or Stylus to a Vite project by installing the preprocessor, share variables with preprocessorOptions, configure PostCSS plugins such as autoprefixer and Tailwind, and fix common import errors.

Plain CSS now has variables, nesting and color-mix(), but many projects still use a preprocessor (Sass, Less, Stylus) for mixins, functions and partials, and PostCSS for transformations like vendor prefixes or utility frameworks. Vite supports all of them with almost no setup, as long as you know which pieces are built in and which you install.

Vite is not installed on this site, so the setup commands and config are read-only. The runnable examples are stand-ins that model what a preprocessor and a PostCSS plugin do to text.

Preprocessors: install the compiler, change the extension

Vite has built-in support for .scss, .sass, .less, .styl and .stylus files. It does not bundle the compilers; you install the one you want as a dev dependency:

Terminal
npm add -D sass-embedded     # Sass (.scss and .sass), the recommended fast package
# or: npm add -D sass         # the pure JavaScript Dart Sass
npm add -D less              # Less
npm add -D stylus            # Stylus

That is the whole setup. Rename style.css to style.scss and import it:

JavaScript
import './style.scss';
SCSS
// style.scss
$brand: #0a7;

@mixin pill($bg) {
  background: $bg;
  border-radius: 999px;
  padding: 0.25rem 0.75rem;
}

.badge {
  @include pill($brand);
  &:hover { filter: brightness(1.1); }
  .icon { margin-right: 0.25rem; }
}

All the CSS features from Importing CSS and CSS Modules work with preprocessors too: HMR, extraction, CSS Modules (card.module.scss), ?inline and aliases.

If you forget to install the compiler, the error message names the missing package (for example, Preprocessor dependency "sass-embedded" not found). Install it and restart the dev server.

A tiny preprocessor, as a model

Preprocessors compile an extended language into plain CSS. This stand-in handles just variables and nesting to show the transformation. It is a teaching model, not Sass.

Node.js Stand-in: variables and nesting to CSS

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Shared variables and mixins everywhere

Importing variables.scss at the top of every file is tedious. css.preprocessorOptions injects code into every file of that type:

JavaScript
// vite.config.js
export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@use "@/styles/variables" as *;`,
        api: 'modern-compiler',
      },
      less: {
        modifyVars: { 'primary-color': '#0a7' },
        javascriptEnabled: true,
      },
    },
  },
});

additionalData is prepended to each file, so variables are available without an import. Use it for variables and mixins only, never for rules that emit CSS, or the same CSS will be repeated in every file.

Sass has moved from @import to @use and @forward. Use @use "./colors" as c; and refer to c.$brand. Vite supports the modern Sass API (api: 'modern-compiler', the default with sass-embedded in recent versions), and the old @import produces deprecation warnings.

Aliases work in Sass imports: @use "@/styles/vars" works when @ is a Vite alias (Vite adds an importer for it). In older versions or with url() references inside Sass, use relative paths or a ~ prefix, depending on the preprocessor.

PostCSS

PostCSS parses CSS into a tree that plugins can change. Vite always runs PostCSS over your CSS. Even with no config it already handles @import inlining and CSS Modules. If your project has a postcss.config.js (or .postcssrc, or a postcss key in package.json), Vite loads it and applies the listed plugins.

JavaScript
// postcss.config.js
export default {
  plugins: {
    'postcss-nested': {},
    autoprefixer: {},
  },
};

Or define it inline in the Vite config and skip the file:

JavaScript
import autoprefixer from 'autoprefixer';

export default defineConfig({
  css: {
    postcss: {
      plugins: [autoprefixer()],
    },
  },
});

If you pass css.postcss as an object, Vite will not look for external PostCSS config files.

Common PostCSS plugins

Plugin Purpose
autoprefixer Adds vendor prefixes for your Browserslist targets
postcss-nesting Native-CSS-style nesting for older targets
postcss-preset-env Lets you write future CSS and compiles it for target browsers
cssnano Heavy minification (esbuild or Lightning CSS already minify well)
tailwindcss / @tailwindcss/postcss Utility-first CSS framework (Tailwind v4 also has a dedicated Vite plugin, @tailwindcss/vite)
postcss-import Inlines @import; Vite already does this

Plugins run in array order, so list them in the order that makes sense (for example, nesting before prefixing).

Here is a PostCSS plugin in miniature, with the real shape: a function that gets the CSS tree and edits declarations. This stand-in does it with text so it runs anywhere.

Node.js Stand-in: a vendor-prefix plugin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Tailwind CSS and Vite

Tailwind CSS v4 provides a first-party Vite plugin, which is faster than the PostCSS route:

JavaScript
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});
CSS
/* main.css */
@import "tailwindcss";

Older Tailwind v3 projects use the PostCSS plugin with a tailwind.config.js. The CSS you write is the same in both worlds, but check the docs for the version you use.

Lightning CSS as a PostCSS alternative

JavaScript
export default defineConfig({
  css: { transformer: 'lightningcss' },
  build: { cssMinify: 'lightningcss' },
});

Lightning CSS is a Rust tool that can minify, add prefixes, lower modern syntax and process CSS Modules in one fast pass. When it is on, Vite does not use PostCSS for the same job (PostCSS plugins configured explicitly still run first). It is a good default for new projects with no PostCSS-specific plugin needs.

Troubleshooting

  • "Preprocessor dependency not found": install sass-embedded, less or stylus.
  • Variables undefined in a module: add additionalData or @use the file.
  • Sass @import warnings: migrate to @use.
  • Prefixes missing: check browserslist in package.json; autoprefixer reads it.
  • PostCSS config ignored: an object in css.postcss disables file-based config.
  • Slow Sass: use sass-embedded and api: 'modern-compiler'.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must you do to use .scss files in Vite?

    Vite recognizes .scss files but needs the compiler package installed.
  2. 2. What is css.preprocessorOptions.scss.additionalData useful for?

    It injects the given code at the start of each file so shared variables are available everywhere.
  3. 3. In what order do PostCSS plugins run?

    Plugins run in array order, so sequence matters, for example nesting before prefixing.
  4. 4. What happens if you set css.postcss to an object in vite.config.js?

    An inline css.postcss object takes over, and external config files are not searched.

Summary

  • Install sass-embedded, less or stylus and import .scss, .less or .styl files; no plugin is needed.
  • Use css.preprocessorOptions and additionalData to share variables and mixins, but never emit CSS from them.
  • PostCSS always runs; configure plugins in postcss.config.js or inline in css.postcss.
  • Tailwind v4 has its own Vite plugin, and Lightning CSS can replace PostCSS for many jobs.
  • Most errors come from a missing compiler, undefined variables or ignored PostCSS config.

Next: Asset URLs and Glob Imports