rollup-plugin-styles

Universal Rollup plugin for styles:

PostCSS
Sass
Less
Stylus
CSS Modules
URL resolving/rewriting with asset handling
Ability to use @import statements inside regular CSS

...and more!

Installation

# npm
npm install -D rollup-plugin-styles
# pnpm
pnpm add -D rollup-plugin-styles
# yarn
yarn add rollup-plugin-styles --dev

Usage

// rollup.config.js
import styles from "rollup-plugin-styles";

export default {
  output: {
    // Governs names of CSS files (for assets from CSS use `hash` option for url handler).
    // Note: using value below will put `.css` files near js,
    // but make sure to adjust `hash`, `assetDir` and `publicPath`
    // options for url handler accordingly.
    assetFileNames: "[name]-[hash][extname]",
  },
  plugins: [styles()],
};

After that you can import CSS files in your code:

import "./style.css";

Default mode is inject, which means CSS is embedded inside JS and injected into <head> at runtime, with ability to pass options to CSS injector or even pass your own injector.

CSS is available as default export in inject and extract modes, but if CSS Modules are enabled you need to use named css export.

// Injects CSS, also available as `style` in this example
import style from "./style.css";
// Using named export of CSS string
import { css } from "./style.css";

In emit mode none of the exports are available as CSS is purely processed and passed along the build pipeline, which is useful if you want to preprocess CSS before using it with CSS consuming plugins, e.g. rollup-plugin-lit-css.

PostCSS configuration files will be found and loaded automatically, but this behavior is configurable using config option.

Importing a file

CSS/Stylus

/* Import from `node_modules` */
@import "bulma/css/bulma";
/* Local import */
@import "./custom";
/* ...or (if no package named `custom` in `node_modules`) */
@import "custom";

Sass/Less

You can prepend the path with ~ to resolve in node_modules:

// Import from `node_modules`
@import "~bulma/css/bulma";
// Local import
@import "./custom";
// ...or
@import "custom";

Also note that partials are considered first, e.g.

@import "custom";

Will look for _custom first (with the appropriate extension(s)), and then for custom if _custom doesn't exist.

CSS Injection

styles({
  mode: "inject", // Unnecessary, set by default
  // ...or with custom options for injector
  mode: [
    "inject",
    { container: "body", singleTag: true, prepend: true, attributes: { id: "global" } },
  ],
  // ...or with custom injector
  mode: ["inject", (varname, id) => `console.log(${varname},${JSON.stringify(id)})`],
});

CSS Extraction

styles({
  mode: "extract",
  // ... or with relative to output dir/output file's basedir (but not outside of it)
  mode: ["extract", "awesome-bundle.css"],
});

Emitting processed CSS

// rollup.config.js
import styles from "rollup-plugin-styles";

// Any plugin which consumes pure CSS
import litcss from "rollup-plugin-lit-css";

export default {
  plugins: [
    styles({ mode: "emit" }),

    // Make sure to list it after this one
    litcss(),
  ],
};

CSS Modules

styles({
  modules: true,
  // ...or with custom options
  modules: {},
  // ...additionally using autoModules
  autoModules: true,
  // ...with custom regex
  autoModules: /\.mod\.\S+$/,
  // ...or custom function
  autoModules: id => id.includes(".modular."),
});

With Sass/Less/Stylus

Install corresponding dependency:

For Sass support install sass or node-sass:

# npm
npm install -D sass
# pnpm
pnpm add -D sass
# yarn
yarn add sass --dev

# npm
npm install -D node-sass
# pnpm
pnpm add -D node-sass
# yarn
yarn add node-sass --dev

For Less support install less:

# npm
npm install -D less
# pnpm
pnpm add -D less
# yarn
yarn add less --dev

For Stylus support install stylus:

# npm
npm install -D stylus
# pnpm
pnpm add -D stylus
# yarn
yarn add stylus --dev

That's it, now you can import .scss .sass .less .styl .stylus files in your code.

Configuration

See API Reference for Options for full list of available options.

Why

Because alternatives did not look good enough - they are either too basic, too buggy or poorly maintained.

For example, the main alternative (and inspiration) is rollup-plugin-postcss, but at the time it is not actively maintained, has a bunch of critical bugs and subjectively lacks some useful features and quality of life improvements which should be a part of it.

With that said, here is the basic list of things which differentiate this plugin from the aforementioned one:

Written completely in TypeScript
Up-to-date CSS Modules implementation
Built-in @import handler
Built-in assets handler
Ability to emit pure CSS for other plugins
Complete code splitting support, with respect for multiple entries, preserveModules and manualChunks
Multiple instances support, with check for already processed files
Proper sourcemaps, with included sources content by default
Respects assetFileNames for CSS file names
Respects sourcemaps from loaded files
Support for implementation forcing for Sass
Support for partials and ~ in Less import statements
More smaller things that I forgot

License

Thanks

rollup-plugin-postcss - for good reference
rollup - for awesome bundler

Project Name	Stars	Repos Using This	Packages Using This	Most Recent Commit	Total Releases	Latest Release	Open Issues	License	Language
Hover	27,440	356	24	4 months ago	9	June 11, 2018	40	other	SCSS
A collection of CSS3 powered hover effects to be applied to links, buttons, logos, SVG, featured images and so on. Easily apply to your own elements, modify or just use for inspiration. Available in CSS, Sass, and LESS.
Madge	7,048	1,662	511	a month ago	72	June 23, 2021	77	mit	JavaScript
Create graphs from your CommonJS, AMD or ES6 module dependencies
Balloon.css	4,810	211	88	2 years ago	21	June 30, 2020	20	mit	CSS
Simple tooltips made of pure CSS
Koala	3,988			a year ago			390	other	JavaScript
Koala is a GUI application for less, sass and coffeescript compilation, to help web developers to the development more efficient.
Rfs	3,133	35	31	7 days ago	46	September 07, 2021	5	mit	CSS
✩ Automates responsive resizing ✩
Webpack Encore	2,130	1,762	68	a month ago	73	September 14, 2022	207	mit	JavaScript
A simple but powerful API for processing & compiling assets built around Webpack
Reactql	1,833			4 months ago	71	November 18, 2017	41	mit	TypeScript
Universal React+GraphQL starter kit: React 16, Apollo 2, MobX, Emotion, Webpack 4, GraphQL Code Generator, React Router 4, PostCSS, SSR
Svg Sprite	1,795	1,107	287	11 days ago	85	September 27, 2022	37	mit	JavaScript
SVG sprites & stacks galore — A low-level Node.js module that takes a bunch of SVG files, optimizes them and bakes them into SVG sprites of several types along with suitable stylesheet resources (e.g. CSS, Sass, LESS, Stylus, etc.)
Simple Line Icons	1,761	3,017	351	3 years ago	16	August 10, 2020	29	mit	CSS
Simple and Minimal Line Icons
Static Site Boilerplate	1,663			a year ago	2	January 25, 2019	15	mit	JavaScript
A better workflow for building modern static websites.

Rollup Plugin Styles