Package Exports

rollup-plugin-styles

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (rollup-plugin-styles) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 much more!

Installation
Usage
Configuration
Main differences from rollup-plugin-postcss
Contributing
License
Thanks

Installation

npm install -D rollup-plugin-styles # npm

pnpm add -D rollup-plugin-styles # pnpm

yarn add rollup-plugin-styles --dev # yarn 1.x

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";
// 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 approptiate 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 }],
  // ...or with custom injector
  mode: ["inject", yourInjectorFn],
});

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 node-sass or sass:

npm install -D node-sass # npm

pnpm add -D node-sass # pnpm

yarn add node-sass --dev # yarn 1.x

npm install -D sass # npm

pnpm add -D sass # pnpm

yarn add sass --dev # yarn 1.x

For Less support install less:

npm install -D less # npm

pnpm add -D less # pnpm

yarn add less --dev # yarn 1.x

For Stylus support install stylus:

npm install -D stylus # npm

pnpm add -D stylus # pnpm

yarn add stylus --dev # yarn 1.x

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

`fibers` (Sass only)

By default, fibers package will be loaded automatically if available when using sass implementation.

When installed via npm, Dart Sass supports a JavaScript API that's fully compatible with Node Sass <...>, with support for both the render() and renderSync() functions. <...>

Note however that by default, renderSync() is more than twice as fast as render() due to the overhead of asynchronous callbacks. To avoid this performance hit, render() can use the fibers package to call asynchronous importers from the synchronous code path.

Source

To install fibers:

npm install -D fibers # npm

pnpm add -D fibers # pnpm

yarn add fibers --dev # yarn 1.x

Configuration

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

Main differences from rollup-plugin-postcss

Written completely in TypeScript
Up-to-date CSS Modules implementation
Built-in @import handler
Built-in assets handler
Respects output.assetFileNames
Code splitting support
Multi entry support
Ability to emit pure CSS for other plugins
Correct multiple instance support with check for already processed files
Support for implementation and fibers forcing for Sass
Support for partials and ~ in Less import statements
Sourcemaps include source content
Proper sourcemap generation for all loaders
Correct inline sourcemaps
Correct relative source paths in extracted sourcemaps
Extracts sourcemaps from loaded files
More smaller things that I forgot

Contributing

Any contributions are always welcome, not only Pull Requests! 😀

QA: file bug reports, the more details you can give the better
Code: take a look at the open issues, even if you can't write code showing that you care about a given issue matters
Ideas: feature requests are welcome, even ambitious ones
Donations: financial support helps to dedicate more time to this project

Your First Contribution? You can learn how from this free series, How to Contribute to an Open Source Project on GitHub.

License

Thanks

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