Enable Sass preprocessing in a Vite project

Desired outcome

Enable Sass (.scss/.sass) preprocessing in a Vite‑powered frontend project so that styles are compiled automatically during development and production builds.

Prerequisites

• Node.js >= 18 (or the version your project uses)
• npm or yarn installed
• An existing Vite project created with npm create vite@latest or similar
• Basic familiarity with editing JavaScript/TypeScript and importing CSS

Procedure

1. Add the Sass compiler as a dev dependency:

   # Run in the project root
   npm i -D sass   # or: yarn add -D sass
   

   This installs Dart Sass, which Vite’s built‑in CSS pipeline uses automatically.

2. Import or reference Sass files:
   • In a JavaScript/TypeScript entry point: import './styles/main.scss';
   • In a Vue single‑file component: <style lang="scss">
   • In a Svelte component: <style lang="scss">

   No additional Vite configuration is required for basic Sass support.

3. Verify hot‑module replacement (HMR) in development:

   npm run dev   # or: yarn dev
   

   Edit a .scss file and save; the browser should update the style instantly without a full page reload. Open DevTools → Network → look for an HMR update or check the console for “[Vite] HMR update”.

4. Confirm production build output:

   npm run build   # or: yarn build
   

   Inspect the generated dist/assets/*.css file (or the path configured by build.outDir). The file should contain plain CSS, no Sass syntax. If build.sourcemap is true, a corresponding .css.map file will be present.

Expected checks

• During dev, no Sass syntax errors appear in the console; changes trigger HMR.
• The dev server logs show “css preprocessor: sass” (Vite prints this when it detects the Sass dependency).
• After build, the assets directory contains only .css (and optionally .css.map) files.
• File size of the compiled CSS is reasonable; source maps can be opened in DevTools to map back to original Sass lines.

Recovery / rollback options

If you need to disable Sass support:

1. Remove the dev dependency:

   npm uninstall -D sass   # or: yarn remove -D sass
   

2. Delete or rename any .scss/.sass files you no longer wish to use, or change imports to plain CSS.
3. Restart the dev server and rebuild; Vite will fall back to treating the files as plain CSS (or will report missing module errors if imports remain).
4. Commit the changes to your version‑control system to retain a known‑good state.

Limitations and practical tips

• Using an outdated Sass version (< 1.0) may cause compatibility errors; prefer Dart Sass 1.60 or newer.
• Large projects with deep @use chains can increase dev‑server start time; consider splitting styles into smaller partials or enabling css.devSourcemap only when debugging.
• If you add custom PostCSS plugins, ensure they are listed after the Sass loader in css.preprocessorOptions to avoid processing order issues.