rollup-plugin-hot-css

0.7.2 verified Mon Apr 27 auth: no javascript

A Rollup plugin for loading CSS files with Hot Module Replacement (HMR) support via Nollup. Version 0.7.2 is the latest release. It supports preprocessing with built-in scss and less loaders or custom loaders (including PostCSS), resolves asset URLs (images, fonts), and emits them as Rollup assets. HMR works by replacing the <link> tag href with a timestamp to force browser reload. Differentiates from other CSS plugins by focusing on HMR with Nollup and flexible loader chaining.

Common errors

error Error: Cannot find module 'sass' ↓

cause The SCSS loader requires the 'sass' npm package to be installed but it is missing.

fix

npm install sass --save-dev

error Error: No loader found for .css ↓

cause The 'extensions' option does not include '.css' or loaders array is missing a suitable loader.

fix

Add '.css' to extensions and ensure a loader is present (e.g., loaders: [] for plain CSS).

error TypeError: hotcss is not a function ↓

cause Using ES import syntax with a package that only exports CommonJS.

fix

Use require() or configuration with bundler that handles CJS interop.

error The 'hot' option is deprecated. Use HMR through Nollup only. ↓

cause Confusion with other Rollup HMR plugins; this plugin's hot option works only with Nollup.

fix

Ensure you are using Nollup dev server. For Rollup-only builds, set hot: false.

Warnings

breaking HMR only works with Nollup dev server, not Rollup's built-in watcher. Using hot:true without Nollup will cause errors. ↓

fix Set hot: false for production builds, or use Nollup development server.

gotcha Asset URLs are resolved only if sourcemaps are emitted by the previous loader. If missing, URLs may be broken. ↓

fix Ensure each loader (especially custom ones) returns a sourcemap or disable url: false.

deprecated The 'file' option default is 'styles.css', but final name depends on assetFileNames Rollup output option, which can be confusing. ↓

fix Set assetFileNames to '[name][extname]' to get expected output filename.

gotcha Custom loaders can be async by returning a Promise, but many users forget to wrap resolve correctly in Promise constructor. ↓

fix Always return a Promise object, not an object directly from the executor. Use async/await or new Promise(resolve => resolve({...})).

breaking The 'loaders' array expects string names only for built-in loaders ('scss', 'less'); passing a function works but requires correct signature. ↓

fix For custom loaders, use a function that receives (input, id) and returns { code, map?, watchFiles? }.

Install

npm install rollup-plugin-hot-css

yarn add rollup-plugin-hot-css

pnpm add rollup-plugin-hot-css

Imports

default
wrong
```
const hotcss = require('rollup-plugin-hot-css');
```
correct
```
import hotcss from 'rollup-plugin-hot-css'
```
Package does not ship ESM; use require() in CommonJS or use dynamic import in ESM.

require()

wrong

import hotcss from 'rollup-plugin-hot-css'

correct

const hotcss = require('rollup-plugin-hot-css')

Only CJS is supported. In ESM contexts, use createRequire or transpile.

TypeScript types

wrong

import type { RollupPluginHotCssOptions } from 'rollup-plugin-hot-css'

correct

// @ts-ignore or declare module 'rollup-plugin-hot-css'

Does not include TypeScript declarations. Use custom type declaration or @ts-ignore.

Quickstart

Basic Rollup config using rollup-plugin-hot-css with SCSS preprocessing and HMR.

// rollup.config.js
const hotcss = require('rollup-plugin-hot-css');

module.exports = {
  input: 'src/main.js',
  output: {
    dir: 'dist',
    format: 'esm',
    assetFileNames: '[name][extname]'
  },
  plugins: [
    hotcss({
      file: 'styles.css',
      extensions: ['.css', '.scss'],
      loaders: ['scss'],
      hot: true,
      publicPath: '/'
    })
  ]
};