grunt-reload

    0.2.0 • Public • Published

    grunt-reload

    A grunt task that enables live reloading of updated watch files in the browser.

    Getting Started

    Install this grunt plugin next to your project's grunt.js gruntfile with: npm install grunt-reload

    Then add this line to your project's grunt.js gruntfile:

    grunt.loadNpmTasks('grunt-reload');

    Documentation

    This plugin provides two grunt tasks: 'reload' and 'reloadServer'. 'reload' is designed to be called via the watch task configuration. 'reloadServer' is designed to be called on the command-line along with the watch task.

    The reload task tells the page to refresh itself via websocket connection between the reloadServer task and the reloadClient.js that is appended to the requested html file. When the watch task detects a changed file, it will process its configured tasks, which should include the 'reload' task if it is setup like the example below.

    Configuration:

    • port: (number, default: 8001) Reverse proxy listens on this port. This is necessary for including reload client javascript.
    • proxy: (object, optional) If present, this config object will enable a reverse proxy to your development server's content
      • host: (string, default: 'localhost') development server hostname
      • port: (number, default: server.port or 80) development server port
      • includeReloadScript: (boolean, default: true) includes the client js to listen for reload commands
    • iframe: (object, optional)
      • target: (string) URL of development server
    • liveReload: (boolean, only required for LiveReload 2.x)

    Reload methods

    Proxy

    This will automatically append the script to the requested HTML file. Here's how you would use grunt-reload with grunt-less:

    // project configuration
    grunt.initConfig({
        lint: {
            all:['js/*.js']
        },
        reload: {
            port: 6001,
            proxy: {
                host: 'localhost'
            }
        },
        watch:{
            files:['index.html', 'style.less'],
            tasks:'default reload'
        }
     
    });
     
    grunt.loadNpmTasks('grunt-less');
    grunt.loadNpmTasks('grunt-reload');
     
    grunt.registerTask('default', 'lint less');

    IFrame

    Use this method if you don't want to muck around with your server's response.

    ...
        iframe: {
            target: 'http://localhost:9999'
        }
    ...

    Your iframe'd dev site in this instance would be available at the default http://localhost:8001

    LiveReload extension

    This is useful if you want to reload CSS files in place in addition to the entire page when files change. It requires a LiveReload extension. In-line reloading of CSS requires grunt 4.0.

    Set the reload server to listen on LiveReload's default port:

    ...
        port: 35729, // LR default
        liveReload: {}
    ...

    Make sure you enable LR in your browser (click the LR button in Chrome)

    Manual include

    If you prefer hard-coding over proxies, extensions, and iframes, you can just do this:

    <script>
        __reloadServerUrl="ws://localhost:8001";
    </script> 
    <script type="text/javascript" src="//localhost:8001/__reload/client.js"></script>

    This makes the reload client work from any address.

    Usage

    grunt reload watch

    If you want to run a static server using the bundled server task, and enable reloading, you can configure something like this:

    ...
        reload: {
            port: 6001,
            proxy: {
                host: 'localhost',
                port: 8000 // should match server.port config
            }
        },
        watch:{
            files:['index.html', 'style.less'],
            tasks:'lint less reload'
        }
    ...
    grunt.registerTask('default', 'server reload watch');

    Then just run:

    grunt

    TODO

    • reload resources without refreshing entire page use LiveReload extensions and grunt 4.x alpha
    • add option to run standalone web server for project use server task for now
    • write chrome extension to reload resources (css, images, templates)
      • the includeReloadScript & proxy options will probably become the fallback method of attaching the client
      • may allow one of three attach methods: extension, iframe, or proxy

    Release History

    • 06/15/2012 - 0.2.0: Added support for grunt 4.0, LiveReload extensions, iframes, and custom targets
    • 06/04/2012 - 0.1.2: Removed connect 1.x requirement (no longer using connect.router). Added test. Clean up.
    • 06/03/2012 - 0.1.1: Fixes 'socket hang up' error.
    • 05/27/2012 - 0.1.0: Initial release.

    License

    Copyright (c) 2012 webxl
    Licensed under the MIT license.

    Keywords

    none

    Install

    npm i grunt-reload

    DownloadsWeekly Downloads

    148

    Version

    0.2.0

    License

    none

    Last publish

    Collaborators

    • webxl