Vite Plugin CSS Sourcemap

1.0.5 verified Mon Apr 27 auth: no javascript

A Vite plugin (v1.0.5) that generates CSS sourcemaps during production builds. Unlike Vite's built-in CSS sourcemap support, this plugin provides fine-grained control over sourcemap output location and URL generation, supporting custom extensions like .scss and .less. It hooks into Vite's build pipeline via the `vite:css-post` plugin to emit sourcemap files and add references to CSS output. Requires Vite >=5.0.0 and peer dependencies for Sass processing. Compatible with Vite 5.x and 6.x. Released under MIT license.

Common errors

error Error: The plugin is not working in dev mode ↓

cause Plugin is designed only for build phase.

fix

Use the plugin only in production builds via 'vite build'.

error Error: Cannot find module 'sass' ↓

cause Missing peer dependency for scss processing.

fix

Install sass or sass-embedded: 'npm install sass --save-dev'

error TypeError: cssSourcemap is not a function ↓

cause Incorrect import or require pattern.

fix

Use default import: 'import cssSourcemap from 'vite-plugin-css-sourcemap'' or in CJS: 'const cssSourcemap = require('vite-plugin-css-sourcemap').default'.

Warnings

breaking Plugin only works during build; no effect in dev mode. ↓

fix Use only for production builds with 'vite build'.

gotcha Must set 'build.sourcemap' to true or 'hidden' in Vite config for sourcemaps to be generated. ↓

fix Add 'build.sourcemap: true' to vite.config.

gotcha For .scss files, either 'sass' or 'sass-embedded' must be installed as a dev dependency. ↓

fix Install sass or sass-embedded.

breaking In v1.0.0, entry with no hash could produce null sourcemap; fixed in v1.0.1. ↓

fix Update to v1.0.1 or later.

breaking In v1.0.2, path argument must be a string; earlier versions crashed on non-string paths. ↓

fix Update to v1.0.2 or later.

deprecated The 'enable' option is deprecated; use 'enabled' instead (typo fix). ↓

fix Use 'enabled: true' instead of 'enable: true'.

Install

npm install vite-plugin-css-sourcemap

yarn add vite-plugin-css-sourcemap

pnpm add vite-plugin-css-sourcemap

Imports

default

wrong

import { cssSourcemap } from 'vite-plugin-css-sourcemap'

correct

import cssSourcemap from 'vite-plugin-css-sourcemap'

The plugin is exported as a default export. Named import will fail.

CjsRequire

wrong

const cssSourcemap = require('vite-plugin-css-sourcemap')

correct

const cssSourcemap = require('vite-plugin-css-sourcemap').default

In CommonJS, the default export is under .default. Direct require() gives an object, not the function.

Plugin type
wrong
```
import { Plugin } from 'vite-plugin-css-sourcemap'
```
correct
```
import type { Plugin } from 'vite'
```
Vite plugins have their own Plugin type; the package does not export a custom type.

Quickstart

Basic setup with Vite config including the plugin and enabling build sourcemaps.

// vite.config.ts
import { defineConfig } from 'vite';
import cssSourcemap from 'vite-plugin-css-sourcemap';

export default defineConfig({
  plugins: [cssSourcemap()],
  build: {
    cssCodeSplit: true,
    sourcemap: true,
  },
});

// Ensure at least one CSS file is imported in your project
// Run 'vite build' to produce CSS with sourcemap references