DanielAmenou/rollup-plugin-lib-style

README

rollup-plugin-lib-style

A Rollup plugin for building component libraries with tree-shakeable, per-component CSS. Write your styles in CSS, SASS/SCSS, Less, Stylus, or any other CSS preprocessor -- the plugin extracts scoped CSS modules and generates a separate CSS file for each component. Consumers only pay for the styles they actually use.

Why

There are two common approaches to bundling and distributing styles from a library:

Approach	Drawback
Single CSS file	Consumers must import all styles, even for components they never use. Increases total CSS payload and can cause unused-style bloat.
CSS-in-JS (styled-components, emotion, etc.)	Adds runtime overhead, increases JavaScript bundle size, and can delay first paint since styles are computed at runtime.

rollup-plugin-lib-style takes a fundamentally better approach for libraries: it generates a separate CSS file per component, automatically scoped with CSS modules. This gives you:

Zero runtime cost -- styles are plain CSS files, not JavaScript. No runtime style injection, no extra computation on the client.
Tree-shakeable CSS -- when a consumer imports a component, only that component's CSS is loaded. Unused components contribute zero CSS to the final bundle.
Scoped by default -- CSS module hashing prevents class name collisions between your library and the consuming application, with no extra setup.
Preprocessor agnostic -- works out of the box with CSS and SASS/SCSS, and supports Less, Stylus, and any other preprocessor via custom loaders.
preserveModules-friendly -- each emitted chunk gets a CSS import path computed relative to its own location, so preserving the source module structure, code splitting, and hashed asset names all work out of the box.
No consumer-side configuration -- consumers simply import your components; the CSS is automatically referenced and loaded alongside the JavaScript.

Install

npm install rollup-plugin-lib-style --save-dev

yarn add rollup-plugin-lib-style --dev

Usage

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  plugins: [libStylePlugin()],
}

After adding this plugin, you can use CSS and SASS/SCSS files out of the box. Support for Less, Stylus, and other preprocessors can be added via custom loaders (see loaders).

Each imported style file is transformed into a CSS module. A new .css file is generated alongside a .css.js file that re-exports the class name mappings and imports the CSS.

For example, given this import:

import style from "./style.css"

The plugin transforms it into:

import style from "./style.css.js"

The generated style.css.js file looks like this:

// style.css.js
import "./myComponent/style.css"

var style = {test: "test_cPySKa"}

export {style as default}

This gives consumers the ability to import only the styles they actually use.

Works with `preserveModules`

The plugin resolves each CSS import path per chunk, so it produces correct output regardless of your Rollup output topology:

output.preserveModules: true -- each emitted JS module imports its CSS using a specifier relative to that module's own location, so modules at different nesting depths all resolve correctly.
Single-bundle builds (preserveModules: false) -- works as before.
Multiple output targets, code splitting, nested chunks, and custom assetFileNames -- all supported without extra configuration.

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  input: "src/index.js",
  output: {
    dir: "dist",
    format: "esm",
    preserveModules: true, // works out of the box
  },
  plugins: [libStylePlugin()],
}

Internally, the plugin emits each CSS file as a Rollup asset and rewrites the import specifier during renderChunk using Rollup's authoritative asset file names. This means bundle.write() and bundle.generate() both produce correct output -- no post-build rewrite step is required. The rewrite runs before other renderChunk plugins such as minifiers, so it doesn't matter where you list terser() in plugins.

Options

importCSS

Type: boolean
Default: true
Description: Automatically import the generated CSS file from the JavaScript module.

classNamePrefix

Type: string
Default: ""
Description: A prefix added to all generated class names.

scopedName

Type: string
Default: "[local]_[hash:hex:6]"
Description: Customize the scoped name format for generated class names.
Available placeholders: [local], [hash], [hash:<digest>], [hash:<digest>:<length>], [hash:<length>]
Available digests: "latin1", "hex", "base64"

postCssPlugins

Type: object[]
Default: []
Description: An array of PostCSS plugins to apply during CSS processing.

When PostCSS runs, the plugin sets the standard PostCSS options as follows:

from is the source file's absolute path -- so source maps, dependency tracking, and postcss-modules class hashing all key off the source location, exactly as you'd expect.
to is anchored at the eventual emitted CSS asset's location inside Rollup's output directory (i.e. <output.dir>/<emittedFileName>), not at the source path.

This matters for PostCSS plugins that resolve their own paths relative to to. The most common example is postcss-url: its assetsPath is interpreted relative to to, so anchoring to at the output directory means postcss-url copies referenced files (images, fonts, etc.) to a location that tracks your build output -- not your source tree's nesting.

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"
import postcssUrl from "postcss-url"

export default {
  input: "src/index.js",
  output: {dir: "dist", format: "esm", preserveModules: true},
  plugins: [
    libStylePlugin({
      postCssPlugins: [
        postcssUrl({url: "copy", assetsPath: "../../assets", inline: false}),
      ],
    }),
  ],
}

If you do not set output.dir (or output.file) in your rollup input options -- e.g. you only specify the output through bundle.write({dir: ...}) -- the plugin falls back to the source path for to, preserving the pre-2.6.0 behavior.

sassOptions

Type: object
Default: {}
Description: Options passed to the Sass compiler. Can be used to set loadPaths for global imports and mixins.

Example:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  plugins: [
    libStylePlugin({
      sassOptions: {
        loadPaths: ["./src/styles", "./node_modules"],
      },
    }),
  ],
}

loaders

Type: Loader[]
Default: []
Description: Custom loaders for additional CSS preprocessors like Less, Stylus, etc. Each loader must have a name, a regex to match file extensions, and a process function that returns an object with a code property containing the CSS string.

Example:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

const lessLoader = {
  name: "lessLoader",
  regex: /\.less$/,
  process: ({code, filePath}) => ({code: compileLess(code)}),
}

export default {
  plugins: [libStylePlugin({loaders: [lessLoader]})],
}

You can also override the built-in SCSS loader to customize Sass compilation:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"
import sass from "sass"

const customSassLoader = {
  name: "sass",
  regex: /\.(sass|scss)$/,
  process: ({filePath}) => ({
    code: sass
      .compile(filePath, {
        loadPaths: ["./src/styles", "./node_modules"],
      })
      .css.toString(),
  }),
}

export default {
  plugins: [libStylePlugin({loaders: [customSassLoader]})],
}

include

Type: Array<string | RegExp> | string | RegExp | null
Default: null
Description: A pattern or array of patterns specifying which files to include. By default, all files matched by a loader are included.

exclude

Type: Array<string | RegExp> | string | RegExp | null
Default: null
Description: A pattern or array of patterns specifying which files to exclude from processing.

customCSSPath

Type: (id: string) => string
Default: undefined
Description: A callback to transform the path used for the generated CSS file. This controls where the CSS asset is emitted. The import specifier in the generated JavaScript is automatically computed from this path.

For example, if your source uses .module.scss files but the output should use plain .css, you can strip the .module portion:

libStylePlugin({
  customCSSPath: (id) => id.replace(process.cwd(), "").replace(/\\/g, "/").replace(".module", ""),
})

customPath (legacy)

Type: string
Default: undefined
Description: Legacy option. When set, the plugin switches to its original magic-path behavior, where every CSS import in the output is prefixed with this string. Most users should not need this -- the plugin now computes correct per-chunk relative paths automatically. This option is kept for backward compatibility with existing configurations.

customCSSInjectedPath (legacy)

Type: (id: string) => string
Default: undefined
Description: Legacy option. When set, the plugin switches to the magic-path flow so the injected import specifier can differ from where the CSS file is actually emitted. Most users should not need this; if you want to change the emitted CSS location, use customCSSPath instead. Kept for backward compatibility.

Global Styles

In some cases, you may want class names to remain unscoped (without a hash). You can do this by adding .global to the style file name. For global styles, the scopedName is set to "[local]", preserving the original class name.

Examples: myStyle.global.css, mySecondStyle.global.scss

/* myStyle.global.css */
.myStyle {
  background-color: red;
}

The generated JavaScript module:

// myStyle.global.css.js
import "./myComponent/style.css"

var style = {myStyle: "myStyle"}

export {style as default}

`onwarn` handler (no longer needed)

The plugin resolves its own synthetic imports during the build in both its default and legacy modes, so Rollup emits no unresolved-import warnings and no onwarn handler is required.

Earlier versions warned about unresolved @@_MAGIC_PATH_@@/... imports when customPath or customCSSInjectedPath was set. The exported onwarn handler that suppressed those warnings is still available, so existing configurations keep working:

// rollup.config.js
import {libStylePlugin, onwarn} from "rollup-plugin-lib-style"

export default {
  onwarn, // optional
  plugins: [libStylePlugin({customPath: "."})],
}

Sponsor

If this project helps you, consider supporting development on GitHub Sponsors.

License

MIT © Daniel Amenou

README

rollup-plugin-lib-style

Why

There are two common approaches to bundling and distributing styles from a library:

Approach	Drawback
Single CSS file	Consumers must import all styles, even for components they never use. Increases total CSS payload and can cause unused-style bloat.
CSS-in-JS (styled-components, emotion, etc.)	Adds runtime overhead, increases JavaScript bundle size, and can delay first paint since styles are computed at runtime.

rollup-plugin-lib-style takes a fundamentally better approach for libraries: it generates a separate CSS file per component, automatically scoped with CSS modules. This gives you:

Zero runtime cost -- styles are plain CSS files, not JavaScript. No runtime style injection, no extra computation on the client.
Tree-shakeable CSS -- when a consumer imports a component, only that component's CSS is loaded. Unused components contribute zero CSS to the final bundle.
Scoped by default -- CSS module hashing prevents class name collisions between your library and the consuming application, with no extra setup.
Preprocessor agnostic -- works out of the box with CSS and SASS/SCSS, and supports Less, Stylus, and any other preprocessor via custom loaders.
preserveModules-friendly -- each emitted chunk gets a CSS import path computed relative to its own location, so preserving the source module structure, code splitting, and hashed asset names all work out of the box.
No consumer-side configuration -- consumers simply import your components; the CSS is automatically referenced and loaded alongside the JavaScript.

Install

npm install rollup-plugin-lib-style --save-dev

yarn add rollup-plugin-lib-style --dev

Usage

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  plugins: [libStylePlugin()],
}

After adding this plugin, you can use CSS and SASS/SCSS files out of the box. Support for Less, Stylus, and other preprocessors can be added via custom loaders (see loaders).

Each imported style file is transformed into a CSS module. A new .css file is generated alongside a .css.js file that re-exports the class name mappings and imports the CSS.

For example, given this import:

import style from "./style.css"

The plugin transforms it into:

import style from "./style.css.js"

The generated style.css.js file looks like this:

// style.css.js
import "./myComponent/style.css"

var style = {test: "test_cPySKa"}

export {style as default}

This gives consumers the ability to import only the styles they actually use.

Works with `preserveModules`

The plugin resolves each CSS import path per chunk, so it produces correct output regardless of your Rollup output topology:

output.preserveModules: true -- each emitted JS module imports its CSS using a specifier relative to that module's own location, so modules at different nesting depths all resolve correctly.
Single-bundle builds (preserveModules: false) -- works as before.
Multiple output targets, code splitting, nested chunks, and custom assetFileNames -- all supported without extra configuration.

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  input: "src/index.js",
  output: {
    dir: "dist",
    format: "esm",
    preserveModules: true, // works out of the box
  },
  plugins: [libStylePlugin()],
}

Options

importCSS

Type: boolean
Default: true
Description: Automatically import the generated CSS file from the JavaScript module.

classNamePrefix

Type: string
Default: ""
Description: A prefix added to all generated class names.

scopedName

postCssPlugins

Type: object[]
Default: []
Description: An array of PostCSS plugins to apply during CSS processing.

When PostCSS runs, the plugin sets the standard PostCSS options as follows:

from is the source file's absolute path -- so source maps, dependency tracking, and postcss-modules class hashing all key off the source location, exactly as you'd expect.
to is anchored at the eventual emitted CSS asset's location inside Rollup's output directory (i.e. <output.dir>/<emittedFileName>), not at the source path.

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"
import postcssUrl from "postcss-url"

export default {
  input: "src/index.js",
  output: {dir: "dist", format: "esm", preserveModules: true},
  plugins: [
    libStylePlugin({
      postCssPlugins: [
        postcssUrl({url: "copy", assetsPath: "../../assets", inline: false}),
      ],
    }),
  ],
}

sassOptions

Type: object
Default: {}
Description: Options passed to the Sass compiler. Can be used to set loadPaths for global imports and mixins.

Example:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

export default {
  plugins: [
    libStylePlugin({
      sassOptions: {
        loadPaths: ["./src/styles", "./node_modules"],
      },
    }),
  ],
}

loaders

Example:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"

const lessLoader = {
  name: "lessLoader",
  regex: /\.less$/,
  process: ({code, filePath}) => ({code: compileLess(code)}),
}

export default {
  plugins: [libStylePlugin({loaders: [lessLoader]})],
}

You can also override the built-in SCSS loader to customize Sass compilation:

// rollup.config.js
import {libStylePlugin} from "rollup-plugin-lib-style"
import sass from "sass"

const customSassLoader = {
  name: "sass",
  regex: /\.(sass|scss)$/,
  process: ({filePath}) => ({
    code: sass
      .compile(filePath, {
        loadPaths: ["./src/styles", "./node_modules"],
      })
      .css.toString(),
  }),
}

export default {
  plugins: [libStylePlugin({loaders: [customSassLoader]})],
}

include

exclude

Type: Array<string | RegExp> | string | RegExp | null
Default: null
Description: A pattern or array of patterns specifying which files to exclude from processing.

customCSSPath

For example, if your source uses .module.scss files but the output should use plain .css, you can strip the .module portion:

libStylePlugin({
  customCSSPath: (id) => id.replace(process.cwd(), "").replace(/\\/g, "/").replace(".module", ""),
})

customPath (legacy)

customCSSInjectedPath (legacy)

Global Styles

Examples: myStyle.global.css, mySecondStyle.global.scss

/* myStyle.global.css */
.myStyle {
  background-color: red;
}

The generated JavaScript module:

// myStyle.global.css.js
import "./myComponent/style.css"

var style = {myStyle: "myStyle"}

export {style as default}

`onwarn` handler (no longer needed)

The plugin resolves its own synthetic imports during the build in both its default and legacy modes, so Rollup emits no unresolved-import warnings and no onwarn handler is required.

// rollup.config.js
import {libStylePlugin, onwarn} from "rollup-plugin-lib-style"

export default {
  onwarn, // optional
  plugins: [libStylePlugin({customPath: "."})],
}

Sponsor

If this project helps you, consider supporting development on GitHub Sponsors.