grunt-cdn-switch
Insert switchable Script and Style tags into your HTML that automatically link to Local or CDN resources.
Getting Started
This plugin requires Grunt ~0.4.5
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-cdn-switch --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "cdn_switch" task
Overview
With grunt-cdn-switch
, you can replace <!-- HTML Comment Blocks -->
with HTML templates containing resource links, to files such as JavaScript or CSS. These resources are pulled from a remote CDN repository, stored locally and updated when the CDN file is newer than the local file.
This provides an easy way to develop locally without having to rely on fetching resources from a CDN (especially useful when developing in a coffee shop or on a train. At the same time your resources will can stay up-to-date with the latest versions that the CDN provides.
The typical use case for grunt-cdn-switch
is as follows:
- As a Developer, I would like to use local JavaScript files to develop on my laptop, even when the stability of my Internet connection is poor, so that my flow is not disrupted and I can focus on my work where ever I may be.
- As a Dev-Ops Engineer, I would like to have the code loaded from CDNs when running in production, as I do not wish to create additional load on my server where it is not necessary.
- As a Security Analyst, I would like to store the code locally when building in production, so that I do not have to rely on a CDN using an untrusted security certificate.
For example: the following <!--cdn-switch=javascript-->
can be replace with a list of
<script>
tags.
Before
<!--cdn-switch=javascript-->
After
Basic Local Config
Use a configuration like this when you want to fetch resources "only once" from the CDN, and store them in your local path.
This configuration will:
- Fetch the resources from the CDN (when not found in
local_path
) - Store resources in the
local_path
- Replace the HTML comment block with
<script>
tags linking to thelocal_path
resources
Config:
grunt;
Output:
Fetch_Newer Local Config
Use a configuration like this when you want your local files to stay up-top-date with the CDN.
This configuration will:
- Fetch the resources from the CDN (when newer than resources found in
local_path
) - Store any newer resources in the
local_path
- Replace the HTML comment block with
<script>
tags linking to thelocal_path
resources
Config:
grunt;
Output:
CDN Config
Use a configuration like this when you do not want to store any of the files locally, and you want to include script tags that link to your resources on the CDN.
This configuration will:
- Replace the HTML comment block with
<script>
tags linking to thelocal_path
resources
Config:
grunt;
Output:
Options
options.use_local
Type: boolean
Default value: false
When use_local:true
grunt-cdn-switch will:
- Fetch any files not found in
local_path
- Replace the HTML comment block with
<script>
tags linking to thelocal_path
resources
When use_local:false
grunt-cdn-switch will:
- Download nothing
- Replace the HTML comment block with
<script>
tags linking to the CDN resources
options.use_local.fetch_new
Type: boolean
Default value: false
When options.use_local.fetch_new:true
grunt-cdn-switch will:
- Fetch any files not found in
local_path
- Overwrites any files in
local_path
that are older than the _last-modified) dates of their CDN links - Replace the HTML comment block with
<script>
tags linking to thelocal_path
resources
[name]
options.blocks.When invoked, grunt-cdn-switch looks for HTML Comment Blocks, for example: <!--cdn-switch:javascript-->
and will replace this block with the resources that you list. You can have as many block names for a grunt target as you wish.
Typically you might see one for JavaScript and one for CSS, like this:
grunt;
[name]
.html
options.blocks.Type: String
Default value: 'null`
This string represents an HTML fragment that will wrap the link to your resource. For example: where options.html
is '<script src="{{resource}}"></script>'
, the text {{resource}}
will be replaced by either a CDN or a local resource link.
Thus the output where cdn
equals true
might be:
And the output where cdn
equals false
and local_path
equals /dest/js
might be:
[name]
.local_path
options.blocks.Type: String
Default value: 'null`
This string is the path that your CDN resources will be saved to when fetched, and will also be used to write the HTML block for your resources when use_local
is false
.
Usage Examples
A Detailed Development Example
Here is a more detailed example with comments that uses all of the features of grunt-cdn-switch
.
HTML Before
<!--cdn-switch=css--><!--cdn-switch=javascript-->
Configuration
grunt; // Register the dev target with Gruntgrunt;
Console Output
When running the above config, the console output should look similar to this:
Running "cdn_switch:prod" taskCheck: static/js/c3.min.js>> Write: 'javascript' comment block written to: 'static/index.html'Check: static/css/c3.min.css>> Write: 'css' comment block written to: 'static/index.html'Fetch non-existing: http://cdnjs.cloudflare.com/ajax/libs/c3/0.4.10/c3.min.cssDone fetching/checking resources.>> 'css' files checked-with/fetched-to: 'static/css'Fetch non-existing: http://cdnjs.cloudflare.com/ajax/libs/c3/0.4.10/c3.min.jsDone fetching/checking resources.>> 'javascript' files checked-with/fetched-to: 'static/js'File "static/index.html" created. Done, without errors.
HTML After
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Release History
(Nothing yet)