A Vite plugin for handling CSS sourcemaps. This plugin ensures that CSS sourcemaps are properly generated and referenced in your Vite builds.
Important
This plugin is only meant for the build phase, to generate sourcemap files for your build. It doesn't work on dev mode.
- Automatically generates sourcemaps for CSS files
- Supports custom sourcemap file locations
- Configurable sourcemap URL generation
- Works with Vite's build process
- Compatible with Vite 5.x and 6.x
npm install vite-plugin-css-sourcemap --save-dev # or yarn add vite-plugin-css-sourcemap --dev # or pnpm add vite-plugin-css-sourcemap --save-devAdd the plugin to your Vite configuration:
// vite.config.js import { defineConfig } from 'vite'; import cssSourcemap from 'vite-plugin-css-sourcemap'; export default defineConfig({ plugins: [cssSourcemap()], });The plugin accepts the following options:
cssSourcemap({ // Enable/disable the plugin enabled: true, // Custom extensions to process (default: ['.css', '.scss']) extensions: ['.css', '.scss', '.less'], // Custom folder for sourcemap files folder: 'sourcemaps', // Custom function to generate sourcemap URLs getURL: (fileName) => `sourcemaps/${fileName}`, });| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Enable or disable the plugin |
extensions | string[] | ['.css', '.scss'] | File extensions to process |
folder | string | '' | Custom folder for sourcemap files |
getURL | (fileName: string) => string | (fileName) => fileName | Custom function to generate sourcemap URLs |
// vite.config.js import { defineConfig } from 'vite'; import cssSourcemap from 'vite-plugin-css-sourcemap'; export default defineConfig({ plugins: [cssSourcemap()], });// vite.config.js import { defineConfig } from 'vite'; import cssSourcemap from 'vite-plugin-css-sourcemap'; export default defineConfig({ plugins: [ cssSourcemap({ folder: 'sourcemaps', }), ], });// vite.config.js import { defineConfig } from 'vite'; import cssSourcemap from 'vite-plugin-css-sourcemap'; export default defineConfig({ plugins: [ cssSourcemap({ getURL: (fileName) => `/assets/sourcemaps/${fileName}`, }), ], });// vite.config.js import { defineConfig } from 'vite'; import cssSourcemap from 'vite-plugin-css-sourcemap'; export default defineConfig({ plugins: [ cssSourcemap({ extensions: ['.css', '.scss', '.less'], }), ], });This plugin hooks into Vite's build process to:
- Intercept CSS file processing
- Generate sourcemaps for CSS files
- Emit the sourcemap files to the output directory
- Add sourcemap references to the CSS files
The plugin works by:
- Using the
transformhook to process CSS files and generate sourcemaps - Using the
generateBundlehook to ensure sourcemaps are properly emitted - It observes
vite:css-postplugin, specifically theaugmentChunkHashhook to obtain the future id of the file. - Allows configuring the sourcemap URL based on the provided options
This plugin is compatible with:
- Vite 5.x
- Vite 6.x
MIT