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

Using postcss-cli

1// postcss.config.js
2module.exports = {
3    plugins: [
4        require('postcss-copy')({
5            dest: 'dist'
6        })
7    ]
8};

1$ postcss src/index.css

Using Gulp

1var gulp = require('gulp');
2var postcss = require('gulp-postcss');
3var postcssCopy = require('postcss-copy');
4
5gulp.task('buildCss', function () {
6    var processors = [
7        postcssCopy({
8            basePath: ['src', 'otherSrc']
9            dest: 'dist'
10        })
11    ];
12
13    return gulp
14        .src(['src/**/*.css', 'otherSrc/**/*.css'])
15        .pipe(postcss(processors))
16        .pipe(gulp.dest('dist'));
17});

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

1var copyOpts = {
2    ...,
3    template(fileMeta) {
4        return 'assets/custom-name-' + fileMeta.name + '.' + fileMeta.ext;
5    }
6}

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.

Using the ! key in your CSS:

1.btn {
2    background-image: url('!images/button.jpg');
3}
4.background {
5    background-image: url('!images/background.jpg');
6}

Using a string or array with micromatch support to ignore files:

1// ignore with string
2var copyOpts = {
3    ...,
4    ignore: 'images/*.jpg'
5}
6// ignore with array
7var copyOpts = {
8    ...,
9    ignore: ['images/button.+(jpg|png)', 'images/background.jpg']
10}

Using a custom function:

1// ignore function
2var copyOpts = {
3    ...,
4    ignore(fileMeta, opts) {
5        return (fileMeta.filename.indexOf('images/button.jpg') ||
6                fileMeta.filename.indexOf('images/background.jpg'));
7    }
8}

hashFunction

Define a custom function to create the hash name.

1var copyOpts = {
2    ...,
3    hashFunction(contents) {
4        // borschik
5        return crypto.createHash('sha1')
6            .update(contents)
7            .digest('base64')
8            .replace(/\+/g, '-')
9            .replace(/\//g, '_')
10            .replace(/=/g, '')
11            .replace(/^[+-]+/g, '');
12    }
13};

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).

1var Imagemin = require('imagemin');
2var imageminJpegtran = require('imagemin-jpegtran');
3var imageminPngquant = require('imagemin-pngquant');
4
5var copyOpts = {
6    ...,
7    transform(fileMeta) {
8        if (['jpg', 'png'].indexOf(fileMeta.ext) === -1) {
9            return fileMeta;
10        }
11        return Imagemin.buffer(fileMeta.contents, {
12            plugins: [
13                imageminPngquant(),
14                imageminJpegtran({
15                    progressive: true
16                })
17            ]
18        })
19        .then(result => {
20            fileMeta.contents = result;
21            return fileMeta; // <- important
22        });
23    }
24};

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

1var gulp = require('gulp');
2var postcss = require('gulp-postcss');
3var postcssCopy = require('postcss-copy');
4var postcssImport = require('postcss-import');
5var path = require('path');
6
7gulp.task('buildCss', function () {
8    var processors = [
9        postcssImport(),
10        postcssCopy({
11            basePath: ['src', 'node_modules'],
12            preservePath: true,
13            dest: 'dist'
14        })
15    ];
16
17    return gulp
18        .src('src/**/*.css')
19        .pipe(postcss(processors, {to: 'dist/css/index.css'}))
20        .pipe(gulp.dest('dist/css'));
21});

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:

1. Detect the url in the CSS files

2. Validate url

3. Initialize the fileMeta:

   1{
   2    sourceInputFile, // path to the origin CSS file
   3    sourceValue, // origin asset value taked from the CSS file
   4    filename, // filename normalized without query string
   5    absolutePath, // absolute path of the asset file
   6    fullName, // name of the asset file
   7    path, // relative path of the asset file
   8    name, // name without extension
   9    ext, // extension name
   10    query, // full query string
   11    qparams, // query string params without the char '?'
   12    qhash, // query string hash without the char '#'
   13    basePath // basePath found
   14}

4. Check ignore function

5. Read the asset file (using a cache buffer if exists)

6. Add content property in the fileMeta object

7. Execute custom transform

8. Create hash name based on the custom transform

9. Add hash property in the fileMeta object

10. Define template for the new asset

11. Add resultAbsolutePath and extra properties in the fileMeta object

12. Write in destination

13. 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