Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
fg-loadcss
Advanced tools
fg-loadcss - npm Package Compare versions
Comparing version 1.2.1 to 1.3.0
| /* global module:false */ | ||
| module.exports = function(grunt) { | ||
| require( 'matchdep' ).filterDev( 'grunt-*' ).forEach( grunt.loadNpmTasks ); | ||
| // Project configuration. | ||
@@ -15,3 +17,24 @@ grunt.initConfig({ | ||
| }, | ||
| qunit: { | ||
| concat: { | ||
| dist: { | ||
| files: { | ||
| 'dist/loadCSS.js': ['src/loadCSS.js'], | ||
| 'dist/cssrelpreload.js': ['src/cssrelpreload.js'], | ||
| 'dist/onloadCSS.js': ['src/onloadCSS.js'] | ||
| } | ||
| } | ||
| }, | ||
| uglify: { | ||
| options: { | ||
| preserveComments: /^\!/ | ||
| }, | ||
| dist: { | ||
| files: { | ||
| 'dist/loadCSS.min.js': ['src/loadCSS.js'], | ||
| 'dist/cssrelpreload.min.js': ['src/cssrelpreload.js'], | ||
| 'dist/onloadCSS.min.js': ['src/onloadCSS.js'] | ||
| } | ||
| } | ||
| }, | ||
| qunit: { | ||
| files: ['test/qunit/**/*.html'] | ||
@@ -21,5 +44,3 @@ } | ||
| grunt.loadNpmTasks('grunt-contrib-jshint'); | ||
| grunt.loadNpmTasks('grunt-contrib-qunit'); | ||
| grunt.registerTask('default', ['jshint', 'qunit']); | ||
| grunt.registerTask('default', ['jshint', 'qunit', 'concat', 'uglify']); | ||
| }; |
| { | ||
| "name": "fg-loadcss", | ||
| "version": "1.2.1", | ||
| "version": "1.3.0", | ||
| "description": "A function for loading CSS asynchronously", | ||
@@ -19,4 +19,7 @@ "main": "src/loadCSS.js", | ||
| "grunt-cli": "~0.1.13", | ||
| "matchdep": "^1.0.0", | ||
| "grunt-contrib-jshint": "~0.12.0", | ||
| "grunt-contrib-qunit": "~1.0.1" | ||
| "grunt-contrib-qunit": "~1.0.1", | ||
| "grunt-contrib-uglify": "^0.10.0", | ||
| "grunt-contrib-concat": "^0.5.1" | ||
| }, | ||
@@ -23,0 +26,0 @@ "scripts": { |
150
README.md
| # loadCSS | ||
| A function for loading CSS asynchronously | ||
| [c]2016 @scottjehl, [Filament Group, Inc.](https://www.filamentgroup.com/) | ||
| [c]2017 @scottjehl, @zachleat [Filament Group, Inc.](https://www.filamentgroup.com/) | ||
| Licensed MIT | ||
@@ -9,3 +9,3 @@ | ||
| Referencing CSS files with `link[rel=stylesheet]` or `@import` will cause most browsers to delay page rendering while the stylesheet loads. This is desirable in many cases, but when loading stylesheets that are not critical to the initial rendering of a page, loadCSS (and upcoming web standards mentioned below) allows you to load stylesheets asynchronously, so they don’t block page rendering. | ||
| Referencing CSS stylesheets with `link[rel=stylesheet]` or `@import` causes browsers to delay page rendering while a stylesheet loads. When loading stylesheets that are not critical to the initial rendering of a page, this blocking behavior is undesirable. The new `<link rel="preload">` standard enables us to load stylesheets asynchronously, without blocking rendering, and loadCSS provides a JavaScript polyfill for that feature to allow it to work across browsers, as well as providing its own JavaScript method for loading stylesheets. | ||
@@ -15,34 +15,57 @@ * Latest release: https://github.com/filamentgroup/loadCSS/releases | ||
| ## Basic Usage | ||
| ## Recommended loadCSS Usage | ||
| With the [`loadCSS` function](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js) referenced in your page, simply call the `loadCSS` function and pass it a stylesheet URL: | ||
| LoadCSS is designed for loading CSS that is **not critical** to the initial rendering of the page, and desirable to load in an asynchronous manner. (_For the critical CSS rules, we recommend either inlining that CSS in a `style` element, or referencing it externally and server-pushing it using http/2. [Read more here](https://www.filamentgroup.com/lab/modernizing-delivery.html)_) | ||
| ```css | ||
| loadCSS( "path/to/mystylesheet.css" ); | ||
| The standard markup pattern for loading files asynchronously is: `<link rel="preload">` ([W3C Spec](https://www.w3.org/TR/2015/WD-preload-20150721/)). We recommend using this markup pattern to reference your non-critical CSS files. `loadCSS` and its rel=preload polyfill are designed to enable this markup to work in browsers that don't yet support this feature. | ||
| For each CSS file you'd like to load asynchronously, use a `link` element like this: | ||
| ```html | ||
| <link rel="preload" href="path/to/mystylesheet.css" as="style"> | ||
| ``` | ||
| The code above will insert a new CSS stylesheet `link` *after* the last stylesheet or script that loadCSS finds in the page, and the function will return a reference to that `link` element, should you want to use it later in your script. Multiple calls to loadCSS will reference CSS files in the order they are called, but keep in mind that they may finish loading in a different order than they were called depending on network conditions. | ||
| In browsers that support it, the `rel=preload` attribute will cause the browser to fetch the stylesheet, but it will not **apply** the CSS once it is loaded (it merely fetches it). To address this, we recommend using an `onload` attribute on the `link` that will do that for us as soon as the CSS finishes loading. | ||
| ## Recommended Usage Pattern | ||
| ```html | ||
| <link rel="preload" href="path/to/mystylesheet.css" as="style" onload="this.rel='stylesheet'"> | ||
| ``` | ||
| Browsers are beginning to support a standard markup pattern for loading CSS (and other file types) asynchronously: `<link rel="preload">` ([W3C Spec](https://www.w3.org/TR/2015/WD-preload-20150721/)). We recommend using this markup pattern to reference any CSS files that should be loaded asynchronously, and using `loadCSS` to polyfill support browsers that don't yet support this new feature. | ||
| This step requires JavaScript to be enabled, so we recommend including an ordinary reference to your stylesheet inside a `noscript` element as a fallback. | ||
| The markup for referencing your CSS file looks like this: | ||
| ```html | ||
| <link rel="preload" href="path/to/mystylesheet.css" as="style" onload="this.rel='stylesheet'"> | ||
| <noscript><link rel="stylesheet" href="path/to/mystylesheet.css"></noscript> | ||
| ``` | ||
| After linking to your asynchronous stylesheet(s) this way, include the [loadCSS script](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js), as well as the [loadCSS rel=preload polyfill script](https://github.com/filamentgroup/loadCSS/blob/master/src/cssrelpreload.js) in your page. These can be inlined or linked and http/2-pushed if possible. | ||
| Here's how they would look inlined in the page: | ||
| ```html | ||
| <link rel="preload" href="path/to/mystylesheet.css" as="style" onload="this.rel='stylesheet'"> | ||
| <noscript><link rel="stylesheet" href="path/to/mystylesheet.css"></noscript> | ||
| <script> | ||
| /*! loadCSS. [c]2017 Filament Group, Inc. MIT License */ | ||
| (function(){ ... }()); | ||
| /*! loadCSS rel=preload polyfill. [c]2017 Filament Group, Inc. MIT License */ | ||
| (function(){ ... }()); | ||
| </script> | ||
| ``` | ||
| These scripts will automatically detect if a browser supports `rel=preload`. In browsers that natively support `rel=preload`, these scripts will do nothing, allowing the browser to load and apply the asynchronous CSS (note the `onload` attribute above, which is there to set the `link`'s `rel` attribute to stylesheet once it finishes loading in browsers that support `rel=preload`). In browsers that do not support `rel=preload`, they will find CSS files referenced this way in the DOM and load and apply them asynchronously using the loadCSS function. | ||
| Since `rel=preload` does not apply the CSS on its own (it merely fetches it), there is an `onload` handler on the `link` that will do that for us as soon as the CSS finishes loading. Since this step requires JavaScript, you may want to include an ordinary reference to your CSS file as well, using a `noscript` element to ensure it only applies in non-JavaScript settings. | ||
| Note: regardless of whether the browser supports `rel=preload` or not, a CSS file will be referenced from the same location in the source order as your original `link` element. Keep this in mind, as you may want to place the `link` in a particular location in your `head` element so that the CSS loads with an expected cascade order. Also, any `media` attribute value on the original link element will be retained when the polyfill is in play. | ||
| With that markup in the `head` of your page, include the [loadCSS script](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js), as well as the [loadCSS rel=preload polyfill script](https://github.com/filamentgroup/loadCSS/blob/master/src/cssrelpreload.js) in your page (inline to run right away, or in an external file if the CSS is low-priority). | ||
| You can view a demo of this `rel=preload` pattern here: http://filamentgroup.github.io/loadCSS/test/preload.html | ||
| No further configuration is needed, as these scripts will automatically detect if the browsers supports `rel=preload`, and if it does not, they will find CSS files referenced in the DOM and preload them using loadCSS. In browsers that natively support `rel=preload`, these scripts will do nothing, allowing the browser to load and apply the asynchronous CSS (note the `onload` attribute above, which is there to set the `link`'s `rel` attribute to stylesheet once it finishes loading in browsers that support `rel=preload`). | ||
| Note: regardless of whether the browser supports `rel=preload` or not, your CSS file will be referenced from the same spot in the source order as the original `link` element. Keep this in mind, as you may want to place the `link` in a particular location in your `head` element so that the CSS loads with an expected cascade order. | ||
| ## Manual CSS loading with loadCSS | ||
| You can view a demo of this `rel=preload` pattern here: http://filamentgroup.github.io/loadCSS/test/preload.html | ||
| The [loadCSS.js](https://github.com/filamentgroup/loadCSS/blob/master/src/loadCSS.js) file exposes a global `loadCSS` function that you can call to load CSS files programmatically, when needed. | ||
| ```css | ||
| loadCSS( "path/to/mystylesheet.css" ); | ||
| ``` | ||
| The code above will insert a new CSS stylesheet `link` *after* the last stylesheet or script that it finds in the page, and the function will return a reference to that `link` element, should you want to reference it later in your script. Multiple calls to loadCSS will reference CSS files in the order they are called, but keep in mind that they may finish loading in a different order than they were called. | ||
| ## Function API | ||
@@ -79,102 +102,7 @@ | ||
| loadCSS attempts to load a css file asynchronously in any JavaScript-capable browser. However, some older browsers will block rendering while the stylesheet is loading. This table outlines css loading support and async loading support. | ||
| loadCSS attempts to load a css file asynchronously in any JavaScript-capable browser. However, some older browsers such as Internet Explorer 8 and older will block rendering while the stylesheet is loading. This merely means that the stylesheet will load as if you referenced it with an ordinary link element. | ||
| <table> | ||
| <tr> | ||
| <th>Browser</th> | ||
| <th>CSS Loads Successfully</th> | ||
| <th>CSS Loads without Blocking Render</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Chrome Mac (latest and many recent versions)</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Firefox Desktop (latest and many recent versions)</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Opera Mac (latest and many recent versions)</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Safari Mac (latest and many recent versions)</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Safari iOS (latest and many recent versions)</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Chrome Android 5.x</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Chrome Android 4.x</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Android Browser 2.3</th> | ||
| <th>Yes</th> | ||
| <th>No</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Kindle Fire HD</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>Windows Phone IE 8.1</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 11</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 10</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 9</th> | ||
| <th>Yes</th> | ||
| <th>Yes</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 8</th> | ||
| <th>Yes</th> | ||
| <th>No</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 7</th> | ||
| <th>Yes</th> | ||
| <th>No</th> | ||
| </tr> | ||
| <tr> | ||
| <th>IE 6</th> | ||
| <th>Yes</th> | ||
| <th>No</th> | ||
| </tr> | ||
| </table> | ||
| ### Usage Tips | ||
| We typically use `loadCSS` to load CSS files that are non-critical to the initial rendering of a page. See the [EnhanceJS project Readme](https://github.com/filamentgroup/enhance#enhancejs) for examples of how we typically use it to improve page loading performance (note: the newest `rel=preload` pattern is not yet in that readme, but the concepts are the same). | ||
| #### Contributions and bug fixes | ||
| Both are very much appreciated - especially bug fixes. As for contributions, the goals of this project are to keep things very simple and utilitarian, so if we don't accept a feature addition, it's not necessarily because it's a bad idea. It just may not meet the goals of the project. Thanks! |
@@ -1,2 +0,2 @@ | ||
| /*! CSS rel=preload polyfill. Depends on loadCSS function. [c]2016 @scottjehl, Filament Group, Inc. Licensed MIT */ | ||
| /*! loadCSS rel=preload polyfill. [c]2017 Filament Group, Inc. MIT License */ | ||
| (function( w ){ | ||
@@ -22,3 +22,3 @@ // rel=preload support test | ||
| if( link.rel === "preload" && link.getAttribute( "as" ) === "style" ){ | ||
| w.loadCSS( link.href, link ); | ||
| w.loadCSS( link.href, link, link.getAttribute( "media" ) ); | ||
| link.rel = null; | ||
@@ -25,0 +25,0 @@ } |
@@ -1,2 +0,2 @@ | ||
| /*! loadCSS: load a CSS file asynchronously. [c]2016 @scottjehl, Filament Group, Inc. Licensed MIT */ | ||
| /*! loadCSS. [c]2017 Filament Group, Inc. MIT License */ | ||
| (function(w){ | ||
@@ -3,0 +3,0 @@ "use strict"; |
@@ -1,2 +0,2 @@ | ||
| /*! onloadCSS: adds onload support for asynchronous stylesheets loaded with loadCSS. [c]2016 @zachleat, Filament Group, Inc. Licensed MIT */ | ||
| /*! onloadCSS. (onload callback for loadCSS) [c]2017 Filament Group, Inc. MIT License */ | ||
| /* global navigator */ | ||
@@ -3,0 +3,0 @@ /* exported onloadCSS */ |
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Lines of code
- increased by0.85%
2371
Worsened metrics
- Total package byte prevSize
- decreased by-0.22%
98630
- Dev dependency count
- increased by75%
7
- Number of lines in readme file
- decreased by-40.45%
106
No dependency changes