postcss-copy
An async postcss plugin to copy all assets referenced in CSS files to a custom destination folder and updating the URLs.
Sections |
---|
Install |
Quick Start |
Options |
Custom Hash Function |
Transform |
Using postcss-import |
About lifecyle and the fileMeta object |
Roadmap |
Credits |
Install
With npm do:
$ npm install postcss-copy
Quick Start
postcss-cli
Using// postcss.config.jsmoduleexports = plugins: dest: 'dist' ;
$ postcss src/index.css
Gulp
Usingvar gulp = ;var postcss = ;var postcssCopy = ; gulp;
Options
basePath ({string|array} default = process.cwd())
Define one/many base path for your CSS files.
dest ({string} required)
Define the dest path of your CSS files and assets.
template ({string | function} default = '[hash].[ext][query]')
Define a template name for your final url assets.
- string template
- [hash]: Let you use a hash name based on the contents of the file.
- [name]: Real name of your asset.
- [path]: Original relative path of your asset.
- [ext]: Extension of the asset.
- [query]: Query string.
- [qparams]: Query string params without the
?
. - [qhash]: Query string hash without the
#
.
- function template
var copyOpts = ... { return 'assets/custom-name-' + fileMetaname + '.' + fileMetaext; }
preservePath ({boolean} default = false)
Flag option to notify to postcss-copy that your CSS files destination are going to preserve the directory structure.
It's helpful if you are using postcss-cli
with the --base option or gulp-postcss
with multiple files (e.g: gulp.src('src/**/*.css')
)
ignore ({string | string[] | function} default = [])
Option to ignore assets in your CSS file.
!
key in your CSS:
Using the
micromatch support to ignore files:
Using a string or array with// ignore with stringvar copyOpts = ... ignore: 'images/*.jpg'// ignore with arrayvar copyOpts = ... ignore: 'images/button.+(jpg|png)' 'images/background.jpg'
Using a custom function:
// ignore functionvar copyOpts = ... { return fileMetafilename || fileMetafilename; }
hashFunction
Define a custom function to create the hash name.
var copyOpts = ... { // borschik return crypto ; };
transform
Extend the copy method to apply a transform in the contents (e.g: optimize images).
IMPORTANT: The function must return the fileMeta (modified) or a promise using resolve(fileMeta)
.
var Imagemin = ;var imageminJpegtran = ;var imageminPngquant = ; var copyOpts = ... { if 'jpg' 'png' === -1 return fileMeta; return Imagemin ; };
Using copy with postcss-import
postcss-import is a great plugin that allow us work our css files in a modular way with the same behavior of CommonJS.
One thing more...
postcss-import has the ability of load files from node_modules. If you are using a custom basePath
and you want to
track your assets from node_modules
you need to add the node_modules
folder in the basePath
option:
myProject/
|-- node_modules/
|-- dest/
|-- src/
Full example
var gulp = ;var postcss = ;var postcssCopy = ;var postcssImport = ;var path = ; gulp;
About lifecyle and the fileMeta object
The fileMeta is a literal object with meta information about the copy process. Its information grows with the progress of the copy process.
The lifecyle of the copy process is:
-
Detect the url in the CSS files
-
Validate url
-
Initialize the fileMeta:
sourceInputFile // path to the origin CSS filesourceValue // origin asset value taked from the CSS filefilename // filename normalized without query stringabsolutePath // absolute path of the asset filefullName // name of the asset filepath // relative path of the asset filename // name without extensionext // extension namequery // full query stringqparams // query string params without the char '?'qhash // query string hash without the char '#'basePath // basePath found -
Check ignore function
-
Read the asset file (using a cache buffer if exists)
-
Add
content
property in the fileMeta object -
Execute custom transform
-
Create hash name based on the custom transform
-
Add
hash
property in the fileMeta object -
Define template for the new asset
-
Add
resultAbsolutePath
andextra
properties in the fileMeta object -
Write in destination
-
Write the new URL in the PostCSS node value.
On roadmap
nothing for now :)
Credits
- Thanks to @conradz and his rework plugin rework-assets my inspiration in this plugin.
- Thanks to @MoOx for let me create the copy function in his postcss-url plugin.
- Thanks to @webpack, i take the idea of define templates from his awesome file-loader
- Huge thanks to @TrySound for his work in this project.
License
MIT