{"id":13659767,"url":"https://github.com/jonkemp/gulp-useref","last_synced_at":"2025-05-15T03:07:00.884Z","repository":{"id":13287040,"uuid":"15972887","full_name":"jonkemp/gulp-useref","owner":"jonkemp","description":"Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets.","archived":false,"fork":false,"pushed_at":"2022-03-27T18:50:12.000Z","size":586,"stargazers_count":704,"open_issues_count":39,"forks_count":89,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-28T21:04:40.320Z","etag":null,"topics":["gulp-plugin","useref"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonkemp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-16T16:05:58.000Z","updated_at":"2025-04-19T19:55:35.000Z","dependencies_parsed_at":"2022-09-06T05:20:13.239Z","dependency_job_id":null,"html_url":"https://github.com/jonkemp/gulp-useref","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonkemp%2Fgulp-useref","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonkemp%2Fgulp-useref/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonkemp%2Fgulp-useref/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonkemp%2Fgulp-useref/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonkemp","download_url":"https://codeload.github.com/jonkemp/gulp-useref/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253309339,"owners_count":21887973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gulp-plugin","useref"],"created_at":"2024-08-02T05:01:12.081Z","updated_at":"2025-05-15T03:06:55.835Z","avatar_url":"https://github.com/jonkemp.png","language":"JavaScript","readme":"# [gulp](https://github.com/gulpjs/gulp)-useref ![Build Status](https://github.com/jonkemp/gulp-useref/actions/workflows/main.yml/badge.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/jonkemp/gulp-useref/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/jonkemp/gulp-useref?branch=master)\n\n[![NPM](https://nodei.co/npm/gulp-useref.png?downloads=true)](https://nodei.co/npm/gulp-useref/)\n\n\u003e Parse build blocks in HTML files to replace references to non-optimized scripts or stylesheets with [useref](https://github.com/jonkemp/useref)\n\nInspired by the grunt plugin [grunt-useref](https://github.com/pajtai/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](https://github.com/robrich/gulp-if) to conditionally handle specific types of assets.\n\n\n## What's new in 3.0?\n\nChanges under the hood have made the code more efficient and simplified the API. Since the API has changed, please observe the usage examples below.\n\nIf you get errors like\n\n    TypeError: useref.assets is not a function\n\nor\n\n    TypeError: $.useref.assets is not a function\n\nplease read the Migration Notes below.\n\n## Install\n\nInstall with [npm](https://npmjs.org/package/gulp-useref)\n\n```\nnpm install --save-dev gulp-useref\n```\n\n\n## Usage\n\nThe 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.\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref');\n\ngulp.task('default', function () {\n    return gulp.src('app/*.html')\n        .pipe(useref())\n        .pipe(gulp.dest('dist'));\n});\n```\n\nWith options:\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref');\n\ngulp.task('default', function () {\n    return gulp.src('app/*.html')\n        .pipe(useref({ searchPath: '.tmp' }))\n        .pipe(gulp.dest('dist'));\n});\n```\n\nIf you want to minify your assets or perform some other modification, you can use [gulp-if](https://github.com/robrich/gulp-if) to conditionally handle specific types of assets.\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref'),\n    gulpif = require('gulp-if'),\n    uglify = require('gulp-uglify'),\n    minifyCss = require('gulp-clean-css');\n\ngulp.task('html', function () {\n    return gulp.src('app/*.html')\n        .pipe(useref())\n        .pipe(gulpif('*.js', uglify()))\n        .pipe(gulpif('*.css', minifyCss()))\n        .pipe(gulp.dest('dist'));\n});\n```\n\nBlocks are expressed as:\n\n```html\n\u003c!-- build:\u003ctype\u003e(alternate search path) \u003cpath\u003e \u003cparameters\u003e --\u003e\n... HTML Markup, list of script / link tags.\n\u003c!-- endbuild --\u003e\n```\n\n- **type**: either `js`, `css` or `remove`; `remove` will remove the build block entirely without generating a file\n- **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 `\u003c!-- build:js({path1,path2}) js/lib.js --\u003e`.\n- **path**: the file path of the optimized file, the target output\n- **parameters**: extra parameters that should be added to the tag\n\nAn example of this in completed form can be seen below:\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n    \u003c!-- build:css css/combined.css --\u003e\n    \u003clink href=\"css/one.css\" rel=\"stylesheet\"\u003e\n    \u003clink href=\"css/two.css\" rel=\"stylesheet\"\u003e\n    \u003c!-- endbuild --\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003c!-- build:js scripts/combined.js --\u003e\n    \u003cscript type=\"text/javascript\" src=\"scripts/one.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\" src=\"scripts/two.js\"\u003e\u003c/script\u003e\n    \u003c!-- endbuild --\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nThe resulting HTML would be:\n\n```html\n\u003chtml\u003e\n\u003chead\u003e\n    \u003clink rel=\"stylesheet\" href=\"css/combined.css\"/\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n    \u003cscript src=\"scripts/combined.js\"\u003e\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nSee [useref](https://github.com/jonkemp/useref) for more information.\n\n## API\n\n### useref(options [, transformStream1 [, transformStream2 [, ... ]]])\n\nReturns 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](https://github.com/jonkemp/useref).\n\n### Transform Streams\n\nType: `Stream`  \nDefault: `none`\n\nTransform assets before concat. For example, to integrate source maps:\n\n```js\nvar gulp = require('gulp'),\n    sourcemaps = require('gulp-sourcemaps'),\n    useref = require('gulp-useref'),\n    lazypipe = require('lazypipe');\n\ngulp.task('default', function () {\n    return gulp.src('index.html')\n        .pipe(useref({}, lazypipe().pipe(sourcemaps.init, { loadMaps: true })))\n        .pipe(sourcemaps.write('maps'))\n        .pipe(gulp.dest('dist'));\n});\n```\n\n### Options\n\n#### options.searchPath\n\nType: `String` or `Array`  \nDefault: `none`  \n\nSpecify the location to search for asset files, relative to the current working directory. Can be a string or array of strings.\n\n#### options.base\n\nType: `String`  \nDefault: `process.cwd()`  \n\nSpecify the output folder relative to the cwd.\n\n#### options.noAssets\n\nType: `Boolean`  \nDefault: `false`  \n\nSkip assets and only process the HTML files.\n\n#### options.noconcat\n\nType: `Boolean`  \nDefault: `false`  \n\nSkip concatenation and add all assets to the stream instead.\n\n#### options.newLine\n\nType: `String`  \nDefault: `none`\n\nAdd a string that should separate the concatenated files.\n\n#### options.additionalStreams\n\nType: `Array\u003cStream\u003e`  \nDefault: `none`\n\nUse additional streams as sources of assets. Useful for combining gulp-useref with preprocessing tools. For example, to use with TypeScript:\n\n```javascript\nvar ts = require('gulp-typescript');\n\n// create stream of virtual files\nvar tsStream = gulp.src('src/**/*.ts')\n        .pipe(ts());\n\ngulp.task('default', function () {\n    // use gulp-useref normally\n    return gulp.src('src/index.html')\n        .pipe(useref({ additionalStreams: [tsStream] }))\n        .pipe(gulp.dest('dist'));\n});\n```\n\n#### options.transformPath\n\nType: `Function`  \nDefault: `none`\n\nAdd a transformPath function in case the path needs to be modified before search happens.\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref');\n\ngulp.task('default', function () {\n    return gulp.src('app/*.html')\n        .pipe(useref({\n            transformPath: function(filePath) {\n                return filePath.replace('/rootpath','')\n            }\n        }))\n        .pipe(gulp.dest('dist'));\n});\n```\n\n## Migration from v2 API\n\nIf you upgrade gulp-useref from v2 without changing your gulpfile,\nyou will get errors like this:\n\n    TypeError: $.useref.assets is not a function\n\nor\n\n    TypeError: useref.assets is not a function\n\nFor a simple configuration, you can replace this V2 code:\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref');\n\ngulp.task('default', function () {\n    var assets = useref.assets();\n\n    return gulp.src('app/*.html')\n        .pipe(assets)\n        .pipe(assets.restore())\n        .pipe(useref())\n        .pipe(gulp.dest('dist'));\n});\n```\n\nwith this V3 code:\n\n```js\nvar gulp = require('gulp'),\n    useref = require('gulp-useref');\n\ngulp.task('default', function () {\n    return gulp.src('app/*.html')\n        .pipe(useref())\n        .pipe(gulp.dest('dist'));\n});\n```\n\nIf you were previously using useref in a multi-stage pipe,\nyou may need to rewrite the pipe, since the simplified V3 API\nmay not allow for its previous usage.\n\nIf the gulpfile you are using came from a generator, (for example,\nin JohnPapa's excellent \"opinionated\" HotTowel generator), it may\nbe more practical to go back to that generator project to see\nwhether they have upgraded to the V3 gulp-useref API, rather than\ntrying to understand their pipe.\n\n\n## Notes\n\n* [ClosureCompiler.js](https://github.com/dcodeIO/ClosureCompiler.js) doesn't support Buffers, which means if you want to use [gulp-closure-compiler](https://github.com/sindresorhus/gulp-closure-compiler) you'll have to first write out the `combined.js` to disk. See [this](https://github.com/dcodeIO/ClosureCompiler.js/issues/11) for more information.\n\n\n## Contributing\n\nSee the [CONTRIBUTING Guidelines](https://github.com/jonkemp/gulp-useref/blob/master/CONTRIBUTING.md)\n\n\n## License\n\nMIT © [Jonathan Kemp](http://jonkemp.com)\n","funding_links":[],"categories":["JavaScript","Plugins","插件"],"sub_categories":["Injecting Assets","资源注入"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonkemp%2Fgulp-useref","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonkemp%2Fgulp-useref","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonkemp%2Fgulp-useref/lists"}