• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号
登陆 注册
描述文字

jonkemp/gulp-useref: Parse build blocks in HTML files to replace references to n ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称（OpenSource Name）：

jonkemp/gulp-useref

开源软件地址(OpenSource Url)：

https://github.com/jonkemp/gulp-useref

开源编程语言(OpenSource Language)：

JavaScript 97.8%

开源软件介绍(OpenSource Introduction)：

gulp-useref Build Status Coverage Status

NPM

Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets with useref

Inspired by the grunt plugin grunt-useref. It can handle file concatenation but not minification. Files are then passed down the stream. For minification of assets or other modifications, use gulp-if to conditionally handle specific types of assets.

What's new in 3.0?

Changes under the hood have made the code more efficient and simplified the API. Since the API has changed, please observe the usage examples below.

If you get errors like

TypeError: useref.assets is not a function

or

TypeError: $.useref.assets is not a function

please read the Migration Notes below.

Install

Install with npm

npm install --save-dev gulp-useref

Usage

The following example will parse the build blocks in the HTML, replace them and pass those files through. Assets inside the build blocks will be concatenated and passed through in a stream as well.

var gulp = require('gulp'),
    useref = require('gulp-useref');

gulp.task('default', function () {
    return gulp.src('app/*.html')
        .pipe(useref())
        .pipe(gulp.dest('dist'));
});

With options:

var gulp = require('gulp'),
    useref = require('gulp-useref');

gulp.task('default', function () {
    return gulp.src('app/*.html')
        .pipe(useref({ searchPath: '.tmp' }))
        .pipe(gulp.dest('dist'));
});

If you want to minify your assets or perform some other modification, you can use gulp-if to conditionally handle specific types of assets.

var gulp = require('gulp'),
    useref = require('gulp-useref'),
    gulpif = require('gulp-if'),
    uglify = require('gulp-uglify'),
    minifyCss = require('gulp-clean-css');

gulp.task('html', function () {
    return gulp.src('app/*.html')
        .pipe(useref())
        .pipe(gulpif('*.js', uglify()))
        .pipe(gulpif('*.css', minifyCss()))
        .pipe(gulp.dest('dist'));
});

Blocks are expressed as:

<!-- build:<type>(alternate search path) <path> <parameters> -->
... HTML Markup, list of script / link tags.
<!-- endbuild -->
  • type: either js, css or remove; remove will remove the build block entirely without generating a file
  • alternate search path: (optional) By default the input files are relative to the treated file. Alternate search path allows one to change that. The path can also contain a sequence of paths processed from right to left, using JSON brace array notation e.g <!-- build:js({path1,path2}) js/lib.js -->.
  • path: the file path of the optimized file, the target output
  • parameters: extra parameters that should be added to the tag

An example of this in completed form can be seen below:

<html>
<head>
    <!-- build:css css/combined.css -->
    <link href="css/one.css" rel="stylesheet">
    <link href="css/two.css" rel="stylesheet">
    <!-- endbuild -->
</head>
<body>
    <!-- build:js scripts/combined.js -->
    <script type="text/javascript" src="scripts/one.js"></script>
    <script type="text/javascript" src="scripts/two.js"></script>
    <!-- endbuild -->
</body>
</html>

The resulting HTML would be:

<html>
<head>
    <link rel="stylesheet" href="css/combined.css"/>
</head>
<body>
    <script src="scripts/combined.js"></script>
</body>
</html>

See useref for more information.

API

useref(options [, transformStream1 [, transformStream2 [, ... ]]])

Returns a stream with the asset replaced resulting HTML files as well as the concatenated asset files from the build blocks inside the HTML. Supports all options from useref.

Transform Streams

Type: Stream
Default: none

Transform assets before concat. For example, to integrate source maps:

var gulp = require('gulp'),
    sourcemaps = require('gulp-sourcemaps'),
    useref = require('gulp-useref'),
    lazypipe = require('lazypipe');

gulp.task('default', function () {
    return gulp.src('index.html')
        .pipe(useref({}, lazypipe().pipe(sourcemaps.init, { loadMaps: true })))
        .pipe(sourcemaps.write('maps'))
        .pipe(gulp.dest('dist'));
});

Options

options.searchPath

Type: String or Array
Default: none

Specify the location to search for asset files, relative to the current working directory. Can be a string or array of strings.

options.base

Type: String
Default: process.cwd()

Specify the output folder relative to the cwd.

options.noAssets

Type: Boolean
Default: false

Skip assets and only process the HTML files.

options.noconcat

Type: Boolean
Default: false

Skip concatenation and add all assets to the stream instead.

options.newLine

Type: String
Default: none

Add a string that should separate the concatenated files.

options.additionalStreams

Type: Array<Stream>
Default: none

Use additional streams as sources of assets. Useful for combining gulp-useref with preprocessing tools. For example, to use with TypeScript:

var ts = require('gulp-typescript');

// create stream of virtual files
var tsStream = gulp.src('src/**/*.ts')
        .pipe(ts());

gulp.task('default', function () {
    // use gulp-useref normally
    return gulp.src('src/index.html')
        .pipe(useref({ additionalStreams: [tsStream] }))
        .pipe(gulp.dest('dist'));
});

options.transformPath

Type: Function
Default: none

Add a transformPath function in case the path needs to be modified before search happens.

var gulp = require('gulp'),
    useref = require('gulp-useref');

gulp.task('default', function () {
    return gulp.src('app/*.html')
        .pipe(useref({
            transformPath: function(filePath) {
                return filePath.replace('/rootpath','')
            }
        }))
        .pipe(gulp.dest('dist'));
});

Migration from v2 API

If you upgrade gulp-useref from v2 without changing your gulpfile, you will get errors like this:

TypeError: $.useref.assets is not a function

or

TypeError: useref.assets is not a function

For a simple configuration, you can replace this V2 code:

var gulp = require('gulp'),
    useref = require('gulp-useref');

gulp.task('default', function () {
    var assets = useref.assets();

    return gulp.src('app/*.html')
        .pipe(assets)
        .pipe(assets.restore())
        .pipe(useref())
        .pipe(gulp.dest('dist'));
});

with this V3 code:

var gulp = require('gulp'),
    useref = require('gulp-useref');

gulp.task('default', function () {
    return gulp.src('app/*.html')
        .pipe(useref())
        .pipe(gulp.dest('dist'));
});

If you were previously using useref in a multi-stage pipe, you may need to rewrite the pipe, since the simplified V3 API may not allow for its previous usage.

If the gulpfile you are using came from a generator, (for example, in JohnPapa's excellent "opinionated" HotTowel generator), it may be more practical to go back to that generator project to see whether they have upgraded to the V3 gulp-useref API, rather than trying to understand their pipe.

Notes

Contributing

See the CONTRIBUTING Guidelines

License

MIT © Jonathan Kemp

鲜花
握手
雷人
路过
鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
More+
上一篇：
floatdrop/gulp-watch: Watch, that actually is an endless stream发布时间：2022-06-21
下一篇：
agragregra/OptimizedHTML-5: OptimizedHTML 5 – Lightweight production-ready Gulp ...发布时间：2022-06-21
热门推荐
More+
热门话题
More+
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服（服务时间 9:00～18:00）

在线QQ客服
地址：深圳市南山区西丽大学城创智工业园
电邮：jeky_zhao#qq.com
移动电话：139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap