rollup-copy-transform-css
v2.0.0
Published
Inlining, minifying and other methods for transforming stylesheets when copying them with rollup-plugin-copy.
Downloads
1,884
Maintainers
Readme
rollup-copy-transform-css
Inlining, minifying and other methods for transforming stylesheets when copying them with rollup-plugin-copy, rollup-plugin-css-lit or rollup-plugin-scss-lit.
Synopsis
import copy from 'rollup-plugin-copy';
import { createTransform } from 'rollup-copy-transform-css';
export default {
plugins: [
copy({
targets: [{
src: 'src/main.css',
dest: 'dist',
transform: createTransform({ inline: true, minify: true })
}]
})
]
// the rest of the configuration
}
Installation
Make sure that you use Node.js 14 or newer and Rollup 2 or newer. Use your favourite package manager - NPM, PNPM or Yarn. Make sure that you include rollup-plugin-copy too:
npm i -D rollup-copy-transform-css rollup-plugin-copy
pnpm i -D rollup-copy-transform-css rollup-plugin-copy
yarn add -D rollup-copy-transform-css rollup-plugin-copy
Usage
Edit a rollup.config.js
configuration file, import the createTransform
function, call it to create a transformation method and assign it to the transform
property of the copy target options:
import copy from 'rollup-plugin-copy';
import { createTransform } from 'rollup-copy-transform-css';
const transformCss = createTransform({
inline: true, minify: true, map: { inline: false }
})
export default {
input: 'src/index.js',
output: { file: 'dist/main.js', format: 'iife', sourcemap: true },
plugins: [
copy({
targets: [{
src: 'src/main.css', dest: 'dist', transform: transformCss
}]
})
]
}
Then call rollup
either via the command-line or programmatically.
Creation Options
The following options can be passed in an object to the createTransform
function. Either minifying or inlining or both or custom plugins have to be provided:
minify
Type: Boolean | Object
Default: false
Enables minifying. If an object is specified, it will be passed to the cssnano plugin.
Experimental feature: if the object is set to { fast: true }
, esbuild will be used instead of postcss.
inline
Type: Boolean | Object
Default: false
Enables inlining of stylesheets and other assets. If an object is specified, it will have to include two properties pointing to objects: { stylesheets, assets }
. The stylesheets
objects will be passed to the postcss-import plugin. The assets
objects will be passed to the postcss-url plugin.
Experimental feature: if the object is set to { fast: true }
, esbuild will be used instead of postcss.
plugins
Type: Array<Object>
Default: undefined
An array of PostCSS plugins to fully customise the transformation.
filter
Type: String | Array<String> | Function
Default: undefined
Pattern to match files which will be processed by the transform
function. Can be passed to the transform
function too.
map
Type: Boolean | Object
Default: false
Controls the generation of a source map. Can be passed to the transform
function too.
If set to true
, an inline source map will be included in the output stylesheet. If set to an object, options supported by PostCSS for source maps can be included, with the following extras:
| Property | Default | Description |
| :-------------- | :----------- | :---------- |
| inline
| true
| Appends the source map to the output stylesheet. If set to false
the source map will be written to an external file. |
| dir
| undefined
| Target directory for the external source map. If not set, the .map
extension will be just appended to the stylesheet file name. |
| pathTransform
| undefined
| Allows changing the paths in sources
in the source map. |
The prototype of pathTransform
is:
pathTransform(source: string, mapPath: string): string
It is supposed to adapt the source
path and return it.
Usage Options
The prototype of created transform
method fits the transform
method for rollup-plugin-copy
, with an optional options
object to override the defaults passed to createTransform
:
transform(contents: string, filename: string, options?: object): string
The options may contain map
and filter
properties described above.
An example how to use the options:
const transformCss = createTransform({ inline: true, minify: true })
...
targets: [{
src: 'src/main.css',
dest: 'dist',
transform: (contents, filename) =>
transformCss(contents, filename, { map: true })
}]
How It Works
Uses PostCSS to process the contents of the stylesheet. The minifying is performed by the cssnano plugin. Inlining of other stylesheets imported by the @import
directives is performed by the postcss-import plugin. Inlining of other assets like pictures referred to by absolute or relative URLs is performed by the postcss-url plugin. If an error occurs during the transformation, the whole bundling operation will fail, using the postcss-fail-on-warn plugin.
Passing booleans to the createTransform
function - { minify: true, inline: true }
- will use the defaults. You can override them by passing an object instead of true
:
{
minify: {
preset: ['default', { discardComments: { removeAll: true } }]
},
inline: {
stylesheets: {},
assets: { url: 'inline' }
}
}
Pass options for cssnano to minify
, options for postcss-import to inline.stylesheets
and options for postcss-url to inline.assets
.
Experimental feature: if the minify
or inline
object is set to { fast: true }
, esbuild will be used instead of postcss.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code.
License
Copyright (C) 2022-2024 Ferdinand Prantl
Licensed under the MIT License.