npm package: @liquid-js/gulp-css-copy-assets
Description: A gulp pipe plugin, to copy assets from source css code.
Author: tangshuang
Latest version: 0.1.0

# Gulp Css Copy Assets

A gulp pipe plugin, to copy assets from source css code.

When we use gulp to build css, event scss to css, some images or other type of files are contained in this css code.
This plugin help you to copy these files to your wanted assets dir.
You do not need to care about the relative path in css.

**Notice:** only relative url is supported. For example `../img/a.jpg` is ok, `/img/1.jpg` and `http://domain/img/1.jpg` are not supported.

## Install

```
npm install --save-dev gulp-css-copy-assets
```

## Usage

```
import glup from 'gulp'
import copyAssets from 'gulp-css-copy-assets'

gulp.task('default', () => {
    glup.src('src/style.css')
        .pipe(copyAssets())
        .pipe(gulp.dest('dist'))
})
```

Files contained in `src/style.css` will be copy into `dist` directory. For example, in your css:

```
.test {
    background: url(../img/bg.jpg);
}
```

The `bg.jpg` is in `img` directory. You do not need to pass some options into `copyAssets`. It will find the image by relative path, and put it to `dist` directory. And the output content will be:

```
.test {
    background: url(xxxxxxxxxx.jpg); /* file name is hashed by md5-file */
}
```

**Notice**: the position in pipe lines make sense. For example, when you use sourcemap or rename:

```
glup.src('src/*.css')
    .pipe(sourcemap.init())
    .pipe(copyAssets())
    .pipe(sourcemap.write('.'))
    .pipe(gulp.dest('dist'))
```

Then you will find a `.map` file of the image which is not your wanted. So you must put copyAssets after sourcemap.write action:

```
glup.src('src/*.css')
    .pipe(sourcemap.init())
    .... // some postcss action
    .pipe(sourcemap.write('.'))
    .pipe(copyAssets()) // do this after sourcemap.write
    .pipe(gulp.dest('dist'))
```

## Options

```
copyAssets({
    exts: ['.css', '.min.css'],
    srcdirs: [],
    resolve: '../assets',
    theme: 'blue'
})
```

**options.exts**

*Array*

The file extnames to check. Default is `.css`, but when you minify your css code, you should rewrite this option.

You should know the work principle of pipe stream. If you pass `src/*.css` into gup.src, every src css file will be a chunk in the stream. So the file may be renamed, copied or removed in pipe lines. `options.exts` is to find out the right files (which are in the list of output files), and find out images or other type of files contained in this css files, and rewrite the content in this css files.

```
gulp.src('**/*.css')
    .pipe(cssmin())
    .pipe(rename({
        suffix: '.min',
    }))
    .pipe(copyAssets({
        exts: ['.min.css'],
    }))
    .pipe('dist')
```

**options.srcdirs**

*Array*

The source style files' directories. `glob` is NOT supported.
However, you can use glob to find out directories first, and then pass them to options.srcdirs.

Some times, you may have different paths of css files passed into pipe stream. e.g. `gulp.src('style/**/*.scss')`, which mean images' paths are not relative to source file because of `import`.

```
@import '../scss/settings'

.test{}
```

Images may be contained in `../scss/_settings.scss`, but after you do sass converting, the relative path have been changed. e.g.

```
glup.src('src/style.scss')
    .pipe(sass())
    .pipe(copyAssets()) // images in _settings.scss will not be found.
    .pipe(gulp.dest('dist'))
```

So you can pass options.srcdirs:

```
glup.src('src/style.scss')
    .pipe(sass())
    .pipe(copyAssets({
        srcdirs: [__dirname + '/../scss']
    }))
    .pipe(gulp.dest('dist'))
```

Notice: directories paths in `options.srcdirs` are style files directories, not assets source directories. Assets source paths are found by gulp-css-copy-assets automaticly.

The upper code will help you to find out true images path. The directory in `gulp.src` is not needed.

**options.resolve**

*String*

The output directory of assets, relative to dest directory. For example, your dest directory is 'dist', if you pass options.resolve '../assets', output css will be put in 'dist', and output assets will be in 'assets'. 'dist' and 'assets' are the same level in directory tree.

**options.theme**

*String*

A theme directory which should be considered while looking up for assets. I.e. when referencing an image as `url(../img/image.png)` then it will be looked for a subdirectory with a theme-name which probably contains the image. If theme name is `'blue'`, then the image will also be searched in `url(../img/blue/image.png)`.

## Development

If you want to modify code, just run `npm run build` after your change.