1.0.5 • Public • Published


    compile an optimal index.html preloader for a directory of assets

    this is based on some assumptions

    • Best practice: inline critical path assets for fastest initial load experience capped at 14kb
    • Load all other assets dynamically after that
    • Index payload: app shell loading spash animation inlined with dead simple logic to load JS and CSS
    • Secondary payloads: index.js app logic and index.css app styles
    • Delta payloads detertmined in main app logic (loaded in prev step)


    npm i index-html --save-dev


    index-html package is intended for use with compiled assets, ready for deployment, as a last pass in your asset pipeline to create a decently simple preloader that makes some fair tradeoffs.

    Reccomended usage as an npm script ala:

    "compile": "index-html dist > dist/index.html"

    index-html is a sort of compiler that accepts a src directory for its first argument. Some files are magic:

    • index.js (optional) loaded by index.html first
    • index.css (optional) loaded by index.html after the js completes
    • index.svg (optional) svg file to use for the splash screen animation (inlined in index.html)
    • preload.js (optional) module for preloader scripting (compiled inline to index.html)
    • preload.css (optional) module for preloader scripting (compiled inline to index.html)

    All of this compiles into a minified index.html spashscreen. (if the svg and preload are greater than 14kb the compiler will fail.)


    • Displays one centered animated svg asset. Override with index.svg (defaults dots)
    • Inlines css to do a very basic browser reset. Override with preload.css
    • Lazy loads index.css and index.js
    • Runs a mini rAF event loop for displaying progress and load completion cleanup logic. Override w/ preload.js
    • Page emits complete, which again can be overriddenwith preload.js


    // preload.js
    module.exports = {
      before: function() {
        // just before rAF inits
      draw: function() {
        // called every frame
      complete: function() {
        // called when index.js and index.css have been loaded


    • font preloading
    • spritesheets
    • companion lib for resource eaching (maybe just cache manifest)
    • research service worker, favicon, manifest


    npm i index-html

    DownloadsWeekly Downloads






    Last publish


    • brianleroux