Rollup Plugin: Keep CSS Imports

rollup-plugin-keep-css-imports is a Rollup plugin that allows to maintain the original structure of style imports (CSS, SCSS, or SASS) without altering them during the bundling process.

Why?

It will be helpful for building a components library and want to keep all CSS module imports untouched so consumer decide how to bundle or tree shake them. This plugin support both bundled and preserved modules ESM outputs.

Features

• Keeps style imports unchanged
• Supports CSS, SCSS, and SASS files
• Allows the use of custom output paths and extensions
• Emits assets to the specified output directory
• Supports source maps
• Compatible with PostCSS

Installation

Install via npm:

npm install rollup-plugin-keep-css-imports --save-dev

or via yarn:

yarn add rollup-plugin-keep-css-imports --dev

Usage

Add the plugin to Rollup configuration file:

import keepCssImports from "rollup-plugin-keep-css-imports"

export default {
  input: "src/index.js",
  output: {
    file: "dist/bundle.js",
    format: "esm",
  },
  plugins: [
    keepCssImports({
      // Plugin options go here
    }),
  ],
}

Options

Input Options

includeRegexp

| | | | -------- | -------------------- | | Type: | RegExp | | Default: | /\.(?:s[ca]|c)ss$/ |

Regular expression to test if an import should be processed by this plugin

OutputOptions

outputExt

| | | | -------- | -------- | | Type: | string | | Default: | ".css" |

Specifies the file extension for the output CSS files. This is typically ".css" but can be changed if needed.

outputDir

| | | | -------- | -------- | | Type: | string | | Default: | "./" |

Specifies the output directory for the generated CSS files. Relative to Rollup output folder.

outputPath

| | | | -------- | ---------------------------------- | | Type: | "keep" | string | function | | Default: | "keep" |

Specifies the output path relative to outputDir for the generated CSS files. The default value, "keep", preserves the original file paths. It is also possible to provide a custom function to generate output paths based on the input file.

Example:

import keepCssImports from "rollup-plugin-keep-css-imports"
import path from "path"

export default {
  input: "src/index.js",
  output: {
    file: "dist/bundle.js",
    format: "esm",
  },
  plugins: [
    keepCssImports({
      outputPath: (assetId) => {
        // Generate a custom output path based on the input assetId

        // Make the assetId path relative to the current working directory (CWD)
        const relativePath = path.relative(process.cwd(), assetId)

        // Replace 'src' with 'styles' in the relativePath
        const newPath = relativePath.replace("src", "styles")

        // Add a '.min' suffix before the file extension,
        // extension will be replaced with `outputExt` by the plugin
        return newPath.replace(/(\.s[ca]ss)$/, ".min$1")
      },
    }),
  ],
}

sourceMap

| | | | -------- | ----------------------- | | Type: | boolean | "inline" | | Default: | false |

Specifies whether to generate source maps for the compiled CSS. Use "inline" to inline source maps into CSS files.

skipCurrentFolderPart

| | | | -------- | ----------------------- | | Type: | boolean | RegExp | | Default: | false |

By default CSS paths will be prefixed with current folder mark ./. To avoid this for CSS files use true or specify RegExp filter. If RegExp filter matches ./ won't be added to the path. This option may be helpful if you have some issues with external modules imports from node_modules

Extensions' Options

includePaths

| | | | -------- | ------------------- | | Type: | Array<string> | | Default: | ["node_modules/"] |

Specifies the list of include paths for SASS to search when resolving imports.

sass

| | | | -------- | --------------- | | Type: | Sass compiler | | Default: | Dart Sass |

An optional object that allows you to provide a custom SASS implementation, such as Dart SASS or Node SASS. If not specified you must install Dart SASS (npm install sass --save-dev / yarn add sass --dev)

sassOptions

| | | | -------- | ----------- | | Type: | Object | | Default: | undefined |

An optional object that allows to provide additional options for the SASS compiler.

postProcessor

| | | | -------- | ----------- | | Type: | function | | Default: | undefined |

An optional function that allows you to perform additional processing on the generated CSS, such as applying PostCSS plugins.

Example: Use PostCSS with the postcss-url plugin to inline the URLs in the CSS files:

import keepCssImports from "rollup-plugin-keep-css-imports"
import path from "path"
import postcss from "postcss"
import url from "postcss-url"

export default {
  input: "src/index.js",
  output: {
    file: "dist/bundle.js",
    format: "esm",
  },
  plugins: [
    keepCssImports({
      postProcessor: () =>
        postcss([
          url({
            url: "inline",
            basePath: [path.resolve("src"), path.resolve("node_modules")],
          }),
        ]),
    }),
  ],
}

Notes

• Plugin reads preserveModulesRoot property of Rollup output settings, so it can be used to make output tree depth smaller

Supported Rollup versions

Tested with v3 and v4

License

MIT

Copyright (c) 2024 Alexandr Yeskov