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

OverZealous/gulp-cdnizer: A gulp plugin for replacing local links with CDN links ...

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

开源软件名称(OpenSource Name):

OverZealous/gulp-cdnizer

开源软件地址(OpenSource Url):

https://github.com/OverZealous/gulp-cdnizer

开源编程语言(OpenSource Language):

JavaScript 55.1%

开源软件介绍(OpenSource Introduction):

gulp-cdnizer

NPM version Build Status Support via Gratipay

cdnizer plugin for gulp

This plugin will replace local file references in HTML and other files with CDN locations. This allows you to work with local copies of libraries during development, and then automate switching to your CDN version when you deploy your application.

Reporting Issues

If you have issues with the output of this plugin that are not directly related to gulp, please report them to the cdnizer library, not to the gulp plugin!

For example, if you have a development file that looks like this:

<html>
<head>
<script type="text/javascript" src="bower_components/angular/angular.js"></script>

You can use cdnizer to automatically convert it to this during your build process (every change here can be customized):

<html>
<head>
<script>
function cdnizerLoad(u) {
	document.write('<scr'+'ipt src="'+encodeURIComponent(u)+'"></scr'+'ipt>';
}
</script>
<script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/angularjs/1.2.10/angular.min.js"></script>
<script>if(!(angular)) cdnizerLoad("bower_components/angular/angular.js");</script>

Features:

  • It's flexible without being overly complicated.
  • Handles private and multiple public CDNs in the same build.
  • It can use your Bower or NPM installation to determine the correct file versions—no more getting "upgraded" during your build.
  • Provides optional fallback scripts for failed file loading. (By default it can only handle failed JavaScript files, but it's easy to provide a custom solution.)

WARNING

This plugin does not check incoming files. Do not run it on files that you do not want modified.

New & Breaking in version 2.0

  • Support for Node Modules, which is the new default mode
  • If you have the same module in both node_modules and bower_components, and you don't want to use node_modules, you'll need to set the nodeModules property to false in the general config, or set ignoreNodeModules to true in the per-package config.
  • Some default settings have changed, namely allowRev is turned off by default, since it causes too many unexpected errors.

New in version 1.0

cdnizer now can load CDN data from existing *-cdn-data packages, currently google-cdn-data, cdnjs-cdn-data, and jsdelivr-cdn-data. Now you can configure common public CDNs with a single line!

Possible breaking change in 1.0

The version field has been changed in this release. Previously, it was the exact version as it existing within Bower. Now, version is the string major(.minor)?(.patch)?, with any trailing (-beta*, -snapshot*, etc) information removed. (Alpha-numeric characters that are attached to the version string, as in 1.0.0rc1, are not stripped.)

You can still access the full version string via versionFull, which is not modified at all.

Index

Usage

First, install gulp-cdnizer as a development dependency:

npm install --save-dev gulp-cdnizer

Then, add it to your gulpfile.js:

var cdnizer = require("gulp-cdnizer");

gulp.src("./src/index.html")
        .pipe(cdnizer({
            defaultCDNBase: "//my.cdn.host/base",
            allowRev: true,
            allowMin: true,
            files: [

				// This file is on the default CDN, and will replaced with //my.cdn.host/base/js/app.js
				'js/app.js',

				// On Google's public CDN
				{
					file: 'vendor/angular/angular.js',
					package: 'angular',
					test: 'window.angular',
					cdn: '//ajax.googleapis.com/ajax/libs/angularjs/${ version }/angular.min.js'
				},

				// On Firebase's public CDN
				{
					file: 'vendor/firebase/firebase.js',
					test: 'window.Firebase',
					cdn: '//cdn.firebase.com/v0/firebase.js'
				}
			]
        }))
        .pipe(gulp.dest("./dist"));

Alternatively, you can just pass in the files array if you don't need to provide any options, and only have custom files:

gulp.src("./src/index.html")
        .pipe(cdnizer([
            {
                file: 'vendor/angular/angular.js',
                package: 'angular',
                test: 'window.angular',
                // use alternate providers easily
                cdn: '//cdnjs.cloudflare.com/ajax/libs/angularjs/${ version }/angular.min.js'
            },
            {
                file: 'vendor/firebase/firebase.js',
                test: 'window.Firebase',
                cdn: '//cdn.firebase.com/v0/firebase.js'
            }
        ]))
        .pipe(gulp.dest("./dist"));

You can also use globs to define groups of file, and dynamic filename properties:

gulp.src("./src/index.html")
        .pipe(cdnizer([{
                file: 'vendor/angular/*.js',
                package: 'angular',
                test: 'window.angular',
                cdn: '//ajax.googleapis.com/ajax/libs/angularjs/${ version }/${ filenameMin }'
            }]))
        .pipe(gulp.dest("./dist"));

Works great on url()s in CSS files, too:

gulp.src("./src/css/style.css")
        .pipe(cdnizer({
            defaultCDNBase: '//my.cdn.url/',
            relativeRoot: 'css',
            files: ['**/*.{gif,png,jpg,jpeg}']
        }))
        .pipe(gulp.dest("./dist/css/"));

New in v1.0, you can use simplified strings for common public CDNs, like so:

gulp.src("./src/index.html")
        .pipe(cdnizer([
				'google:angular',          // for most libraries, that's all you'll need to do!
				'cdnjs:jquery',
				{
					cdn: 'jsdelivr:yui',   // You can also use a known CDN, while…
					package: 'yui3',       // overriding the package name for Bower, and…
					test: 'window.YUI'     // providing a custom fallback test
				},
				// you can also specify alternate files within a package:
				'jsdelivr:yui:anim-base/[email protected]'
            ]))
        .pipe(gulp.dest("./dist"));

Need multiple files from the one package on a common CDN? Here's two solutions:

// Manually list every file…
gulp.src("./src/index.html")
        .pipe(cdnizer([
				'cdnjs:angular.js:angular.min.js',
				'cdnjs:angular.js:angular-touch.min.js',
				'cdnjs:angular.js:i18n/angular-locale_fr-fr.js'
            ]))
        .pipe(gulp.dest("./dist"));

// Or wire up a pattern:
gulp.src("./src/index.html")
        .pipe(cdnizer([
				// matches all root angular files
				{
					file: '**/angular/*.js',
					cdn: 'cdnjs:angular.js:${ filenameMin }' // Yes, you can apply patterns to the filename!
				},
				// matches all i18n angular files
				{
					file: '**/angular/i18n/*.js',
					cdn: 'cdnjs:angular.js:i18n/${ filename }' // These i18n files are not minified
				}
            ]))
        .pipe(gulp.dest("./dist"));

API

cdnizer( options | files )

Creates a new cdnizer function that can be used to process file contents. You can either pass in a configuration object, or you can pass in an array of files if you don't need to change the default shared options.

See Usage above for examples.

Options

options.defaultCDNBase

Type: String
Default: '' (disabled)

Used for a default, custom CDN, usually for your own files. This will be used in the defaultCDN property to define the default path for a CDN unless overridden.

options.defaultCDN

Type: String
Default: '${ defaultCDNBase }/${ filepathRel }'

This is the default pattern used for generating CDN links when one isn't provided by a specific file.

options.relativeRoot

Type: String
Default: ''

If you are processing a file that references relative files, or is not rooted to the CDN, you must set relativeRoot to get correct results. This relative path will be appended to the file path and the path resolved to remove relative URLs.

For example, if you have a CSS file at style/main.css, and you reference images as ../img/foo.png, you should set relativeRoot to 'style/'. Now if your defaultCDNBase is //example/, the image will be resolved to //example/img/foo.png.

If you do not set relativeRoot when referencing relative files, your files will not match, and they will not be replaced with CDN URLs.

options.allowRev

Type: Boolean
Default: false

Allow for file names with gulp-rev appended strings, in the form of <file>-XXXXXXXX.<ext>. If you are using the gulp-rev plugin, this will automatically match filenames that have a rev string appeneded to them. If you are not using gulp-rev, then you can disable this by setting allowRev to false, which will prevent possible errors in accidentally matching similar file names.

You can always manually configure your globs to include an optional rev string by using the form ?(<rev glob here>), such as name?(-????????).ext for appended revs.

options.allowMin

Type: Boolean
Default: false

Allow for file names that optionally have .min inserted before the file extension (but after rev, if enabled). This allows you to use the base name for a file, and have cndizer match the minified name.

options.fallbackScript

Type: String
Default:

<script>
function cdnizerLoad(u) {
	document.write('<scr'+'ipt src="'+encodeURIComponent(u)+'"></scr'+'ipt>';
}
</script>

Overwrite the default fallback script. If any of the inputs has a fallback, this script is injected before the first occurrence of <link, <script, or </head> in the HTML page. Ignored for files that don't contain <head.

If you already have a script loader (such as yepnope or Modernizr), you can set this to an empty string and override the fallbackTest below to use that instead. Of course, this won't help if you are loading those scripts off a CDN and they fail!

options.fallbackTest

Type: String
Default: '<script>if(!(${ test })) cdnizerLoad("${ filepath }");</script>'

Overwrite the default fallback test. Note that all options availble to options.files[].cdn below are available to this template as well, along with the options.files[].test string.

options.nodeModules

Type: String|Boolean
Default: null

If provided, this is the directory to look for node modules in. If not provided, and there's no existing bower configuration, cdnizer will fall back to node_modules.

If this is set to false, it will not look in node_modules at all.

Once the directory is determined, the script will look for files in <nodeModules>/<package>/package.json to try to determine the version of the installed component.

options.bowerComponents

Type: String
Default: null

If provided, this is the directory to look for Bower components in. If not provided, cdnizer will attempt to look for the .bowerrc file, and if that is not found or does not specify a directory, it falls back to './bower_components'. If that's not found, cdnizer falls back to node_modules.

Once the directory is determined, the script will look for files in <bowerComponents>/bower.json or <bowerComponents>/.bower.json to try to determine the version of the installed component.

options.matchers

Type: Array
Default: []

Array of custom matchers. Use this to add extra patterns within which you would like to cdn-ize URLs, for example if you have such URLs in data-attributes. The matchers should include regular expressions with three matching groups:

  1. Leading characters
  2. The actual URL to work on, and
  3. Trailing characters, which should include the end tag if you want a fallback script injected.

Example (matches the data-src attribute in <img> tags):

matchers: [
	{
		pattern: /(<img\s.*?data-src=["'])(.+?)(["'].*?>)/gi,
		//groups: (       leading        )(url)(trailing)
		fallback: false
	}
]

You can also specify just a regular expression. In that case, fallback will default to false.

Equivalent example:

matchers: [
	/(<img\s.*?data-src=["'])(.+?)(["'].*?>)/gi
]

options.cdnDataLibraries

Type: Array Default: []

Future-proof option to add additional *-cdn-data packages. These packages must be in the same format as google-cdn-data. The format is to only include the leading part of the package name, for example, cdnjs-cdn-data would be included as simply 'cdnjs'.

options.excludeAbsolute

Type: Boolean Default: false

In some cases you may have third party of vendor libraries already loaded off a CDN or remote URL that you don't want re-written.

For example given a config like this

cdnizer({
	files: ['**/*.js', '**/*.css'],
	defaultCDNBase: '//examplecdn/',
	excludeAbsolute: true
});

And an index.html like this

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title></title>
		<link href="http://netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet">
	</head>
	<body>
	<h1>Hello World</h1>
	<script src="js/app/app.js"></script>
	</body>
</html>

With this flag enabled cdnizer will avoid re-writing these kind of paths.

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title></title>
		<!-- path has not changed -->
		<link href="http://netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.css" rel="stylesheet">
	</head>
	<body>
	<h1>Hello World</h1>
		<script src="//examplecdn/js/app/app.js"></script> <!-- has the expected CDN base path -->
	</body>
</html>

options.files

Type: Array
Default: (none) required

Array of sources or objects defining sources to cdnize. Each item in the array can be one of three types, a simple glob, a public CDN string, or object hashmap.

options.files.«glob»

When using a glob, if it matches a source, the defaultCDN template is applied. Because there is no test, the script will not have a fallback.

Examples:

'**/*.js' // matches any .js file anywhere
'js/**/*.js' // matches any *.js file under the js folder
'styles/main.css' // only matches styles/main.css, possibly rev'd or min'd based on options
'img/icon/foo??.{png,gif,jpg}' // img/icon/foo10.png, img/icon/fooAA.gif, etc
options.files.«common-cdn»

Public CDN strings make it easy to add known libraries from common public CDN repositories. They always take the form of '<provider>:<package>(:filename)?(@version)?'. Currently, cdnizer has built-in support for Google, cdnjs, and jsDelivr, via the existing packages maintained by Shahar Talmi.

Examples:

'google:jquery'                             // Note that it's all lowercase
'google:[email protected]'                       // provide a version if you are not using Bower OR to override it
'google:angular'
// this loads the angular-touch file from angular on cdnjs
'cdnjs:angular.js:angular-touch.min.js'     // you need `.js` for angular on cdnjs, but not on Google!
'jsdelivr:angularjs'                        // jsdelivr has it different still

The result of these patterns follows the following process:

  1. Look up the package (e.g.: angular) within the correct CDN's cdn-data.
  2. Get the URL for the package with the version set to ${ version }, which allows dynamic replacement of the version later
  3. If we are provided an alternate filename, replace everything in the URL after ${ version }/ with the new filename. This is how you can select alternate files on the CDN.
  4. Set the cdn property to the URL.
  5. Grab everything after ${ version }/—this is assumed to be the filename—and set the file property (i.e.: the glob pattern) to **/«filename».
  6. Set the package property either to a known package (some known packages are mapped to their Bower package name) or to the passed-in package name.
  7. If we know the correct fallback test for a package, use that. Otherwise, don't set a test.
  8. If a version was passed in, store that as well under the version property.

You can also use a common cdn while customizing the result by using a common CDN with the cdn option within a hashmap. You will need to do this if the CDN provider uses a different package name than Bower, or if you want to provide a fallback test (excluding a few popular libraries).

Note: you can use template strings in the :filename portion of the string. However, if you do this, you'll need to


鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

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

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