Giter VIP home page Giter VIP logo

preload-webpack-plugin's Introduction

preload-webpack-plugin

NPM version NPM downloads Dependency Status

preloads-plugin-compressor

A Webpack plugin for automatically wiring up asynchronous (and other types) of JavaScript chunks using <link rel='preload'>. This helps with lazy-loading.

Note: This is an extension plugin for html-webpack-plugin - a plugin that simplifies the creation of HTML files to serve your webpack bundles.

This plugin is a stop-gap until we add support for asynchronous chunk wiring to script-ext-html-webpack-plugin.

Introduction

Preload is a web standard aimed at improving performance and granular loading of resources. It is a declarative fetch that can tell a browser to start fetching a source because a developer knows the resource will be needed soon. Preload: What is it good for? is a recommended read if you haven't used the feature before.

In simple web apps, it's straight-forward to specify static paths to scripts you would like to preload - especially if their names or locations are unlikely to change. In more complex apps, JavaScript can be split into "chunks" (that represent routes or components) at with dynamic names. These names can include hashes, numbers and other properties that can change with each build.

For example, chunk.31132ae6680e598f8879.js.

To make it easier to wire up async chunks for lazy-loading, this plugin offers a drop-in way to wire them up using <link rel='preload'>.

Pre-requisites

This module requires Webpack 2.2.0 and above. It also requires that you're using html-webpack-plugin in your Webpack project.

Installation

First, install the package as a dependency in your package.json:

$ npm install --save-dev preload-webpack-plugin

Alternatively, using yarn:

yarn add -D preload-webpack-plugin

Usage

Next, in your Webpack config, require() the preload plugin as follows:

const PreloadWebpackPlugin = require('preload-webpack-plugin');

and finally, configure the plugin in your Webpack plugins array after HtmlWebpackPlugin:

plugins: [
  new HtmlWebpackPlugin(),
  new PreloadWebpackPlugin()
]  

By default, the plugin will assume async script chunks will be preloaded with as=script. This is the equivalent of:

plugins: [
  new HtmlWebpackPlugin(),
  new PreloadWebpackPlugin({
    rel: 'preload',
    as: 'script',
    include: 'asyncChunks'
  })
]

For a project generating two async scripts with dynamically generated names, such as chunk.31132ae6680e598f8879.js and chunk.d15e7fdfc91b34bb78c4.js, the following preloads will be injected into the document <head>:

<link rel="preload" href="chunk.31132ae6680e598f8879.js" as="script">
<link rel="preload" href="chunk.d15e7fdfc91b34bb78c4.js" as="script">

You can also configure the plugin to preload all chunks (vendor, async, normal chunks) using include:

plugins: [
  new HtmlWebpackPlugin(),
  new PreloadWebpackPlugin({
    rel: 'preload',
    as: 'script',
    include: 'all'
  })
]

In case you work with named chunks, you can explicitly specify which ones to include by passing an array:

plugins: [
  new HtmlWebpackPlugin(),
  new PreloadWebpackPlugin({
    rel: 'preload',
    as: 'script',
    include: ['home']
  })
]

will inject just this:

<link rel="preload" href="home.31132ae6680e598f8879.js" as="script">

Filtering chunks

There may be chunks that you don't want to have preloaded (sourcemaps, for example). Before preloading each chunk, this plugin checks that the file does not match any regex in the fileBlacklist option. The default value of this blacklist is [/\.map/], meaning no sourcemaps will be preloaded. You can easily override this:

new PreloadWebpackPlugin({
  fileBlacklist: [/\.whatever/]
})

Passing your own array will override the default, so if you want to continue filtering sourcemaps along with your own custom settings, you'll need to include the regex for sourcemaps:

new PreloadWebpackPlugin({
  fileBlacklist: [/\.map./, /\.whatever/]
})

Resource Hints

Should you wish to use Resource Hints (such as prefetch) instead of preload, this plugin also supports wiring those up.

Prefetch:

plugins: [
  new HtmlWebpackPlugin(),
  new PreloadWebpackPlugin({
    rel: 'prefetch'
  })
]

For the async chunks mentioned earlier, the plugin would update your HTML to the following:

<link rel="prefetch" href="chunk.31132ae6680e598f8879.js">
<link rel="prefetch" href="chunk.d15e7fdfc91b34bb78c4.js">

Demo

A demo application implementing the PRPL pattern with React that uses this plugin can be found in the demo directory.

Support

If you've found an error in this sample, please file an issue: https://github.com/googlechrome/preload-webpack-plugin/issues

Patches are encouraged, and may be submitted by forking this project and submitting a pull request through GitHub.

Contributing workflow

index.js contains the primary source for the plugin, test contains tests and demo contains demo code.

Test the plugin:

$ npm install
$ npm run test

Lint the plugin:

$ npm run lint
$ npm run lint-fix # fix linting issues

The project is written in ES2015, but does not use a build-step. This may change depending on any Node version support requests posted to the issue tracker.

Additional Notes

  • Be careful not to preload resources a user is unlikely to need. This can waste their bandwidth.
  • Use preload for the current session if you think a user is likely to visit the next page. There is no 100% guarantee preloaded items will end up in the HTTP Cache and read locally beyond this session.
  • If optimising for future sessions, use prefetch and preconnect. Prefetched resources are maintained in the HTTP Cache for at least 5 minutes (in Chrome) regardless of the resource's cachability.

Related plugins

License

Copyright 2017 Google, Inc.

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

preload-webpack-plugin's People

Contributors

addyosmani avatar jackfranklin avatar bekos avatar conorhastings avatar hanford avatar kuldeepkeshwar avatar pd4d10 avatar

Watchers

Steven Hargrove avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.