or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gulp-livereload

Gulp plugin for livereload functionality in web development workflows.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/gulp-livereload@4.0.x

To install, run

npx @tessl/cli install tessl/npm-gulp-livereload@4.0.0

index.mddocs/

Gulp Livereload

Gulp Livereload is a lightweight Gulp plugin that enables livereload functionality for web development workflows. It integrates with the LiveReload Chrome extension and livereload middleware to automatically refresh browser pages when files change during development. The plugin creates a PassThrough stream that monitors file changes and communicates with a tiny-lr server to trigger browser refreshes, supporting both partial page updates and full page reloads.

Package Information

  • Package Name: gulp-livereload
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install --save-dev gulp-livereload

Core Imports

const livereload = require('gulp-livereload');

Basic Usage

const gulp = require('gulp');
const less = require('gulp-less');
const livereload = require('gulp-livereload');

gulp.task('less', function() {
  return gulp.src('less/*.less')
    .pipe(less())
    .pipe(gulp.dest('css'))
    .pipe(livereload());
});

gulp.task('watch', function() {
  livereload.listen();
  gulp.watch('less/*.less', ['less']);
});

Architecture

Gulp Livereload is built around several key components:

  • Stream Interface: Main function creates a PassThrough stream that integrates with Gulp pipelines
  • Server Management: Built-in tiny-lr server that can be started/stopped programmatically
  • File Change Detection: Monitors vinyl file objects and notifies connected browsers
  • Express Integration: Middleware support for direct integration with Express/Connect applications
  • Configuration System: Global options object for customizing server behavior and paths

Capabilities

Stream Creation

Creates a PassThrough stream that monitors file changes and notifies the livereload server.

/**
 * Create a stream for telling the livereload server about changes
 * @param {object|number} [opts] - Configuration options or port number
 * @param {number} [opts.port] - livereload server port
 * @param {string} [opts.host] - livereload server host
 * @param {string} [opts.basePath] - base directory the path will be resolved to
 * @param {boolean} [opts.start] - automatically start the server
 * @param {boolean} [opts.quiet=false] - disable console logging
 * @param {string} [opts.reloadPage="index.html"] - path for full page reload
 * @returns {stream.PassThrough} PassThrough stream in object mode
 */
function livereload(opts);

Usage Examples:

// Basic stream usage
gulp.src('src/**/*.js')
  .pipe(livereload());

// With options
gulp.src('src/**/*.js')
  .pipe(livereload({
    start: true,
    port: 1234,
    basePath: 'dist'
  }));

// Using just port number
gulp.src('src/**/*.js')
  .pipe(livereload(1234));

Server Management

Starts the livereload server for monitoring file changes.

/**
 * Start the livereload server
 * @param {object|number|function} [opts] - Server options, port number, or callback
 * @param {number} [opts.port] - livereload server port
 * @param {string} [opts.host] - livereload server host
 * @param {string} [opts.basePath] - base directory the path will be resolved to
 * @param {boolean} [opts.start] - automatically start the server
 * @param {boolean} [opts.quiet=false] - disable console logging
 * @param {string} [opts.reloadPage="index.html"] - path for full page reload
 * @param {Buffer} [opts.key] - SSL private key for HTTPS server
 * @param {Buffer} [opts.cert] - SSL certificate for HTTPS server
 * @param {function} [cb] - callback function called when server starts
 */
livereload.listen(opts, cb);

Usage Examples:

// Basic server start
livereload.listen();

// With custom port
livereload.listen(1234);

// With full options
livereload.listen({
  port: 1234,
  host: 'localhost',
  basePath: 'dist',
  quiet: true
});

// With callback
livereload.listen(function() {
  console.log('Livereload server started');
});

// HTTPS configuration
const fs = require('fs');
livereload.listen({
  key: fs.readFileSync('dev.key'),
  cert: fs.readFileSync('dev.crt')
});

Manual File Change Notification

Directly notifies the server that a file has changed and should be reloaded.

/**
 * Instruct the server that a file has changed and should be re-downloaded
 * @param {string|object} filePath - File path string or object with path property
 */
livereload.changed(filePath);

Usage Examples:

// Using file path string
livereload.changed('dist/style.css');

// Using vinyl file object
livereload.changed(file); // where file.path exists

// Programmatic usage
const watcher = chokidar.watch('src/**/*');
watcher.on('change', livereload.changed);

Full Page Reload

Triggers a complete page refresh including all assets.

/**
 * Invoke a full page reload, including all assets
 * @param {string} [filePath] - Path to the page to reload, defaults to options.reloadPage
 */
livereload.reload(filePath);

Usage Examples:

// Reload default page (index.html)
livereload.reload();

// Reload specific page
livereload.reload('about.html');

// Programmatic full reload
gulp.task('rebuild', function() {
  // ... build tasks
  livereload.reload();
});

Express Middleware Integration

Direct access to the underlying tiny-lr middleware for Express/Connect integration.

/**
 * Express middleware for livereload functionality
 * Direct reference to tiny-lr middleware
 */
livereload.middleware;

Usage Examples:

const express = require('express');
const app = express();

// Add livereload middleware
app.use(livereload.middleware);

// Alternative with connect-livereload
const connectLivereload = require('connect-livereload');
app.use(connectLivereload({
  port: 35729
}));

Configuration and Server Access

Global configuration options and direct server instance access.

/**
 * Global options object for configuration
 * @type {object}
 * @property {boolean} quiet - Enable/disable debug logging
 * @property {string} reloadPage - The page to reload for full page reloads
 */
livereload.options;

/**
 * Reference to the underlying tiny-lr server instance
 * @type {object|undefined} - undefined when server is not running
 */
livereload.server;

Usage Examples:

// Access and modify global options
livereload.options.quiet = true;
livereload.options.reloadPage = 'main.html';

// Direct server access
if (livereload.server) {
  console.log('Server is running');
  // Access underlying tiny-lr server methods
  livereload.server.close();
}

// Check server status
const isServerRunning = livereload.server !== undefined;

Configuration Options

All configuration options can be passed to either livereload() or livereload.listen():

  • port (number): Server port for the livereload server
  • host (string): Server host for the livereload server
  • basePath (string): Base directory that file paths will be resolved relative to
  • start (boolean): Automatically start the server when creating the stream
  • quiet (boolean, default: false): Disable console logging of reload events
  • reloadPage (string, default: "index.html"): Path to the browser's current page for full page reloads
  • key (Buffer): SSL private key for HTTPS server mode
  • cert (Buffer): SSL certificate for HTTPS server mode

Types

/**
 * Configuration options for livereload
 * @typedef {object} LivereloadOptions
 * @property {number} [port] - Server port
 * @property {string} [host] - Server host
 * @property {string} [basePath] - Base directory for path resolution
 * @property {boolean} [start] - Automatically start server
 * @property {boolean} [quiet=false] - Disable console logging
 * @property {string} [reloadPage="index.html"] - Default page for full reload
 * @property {Buffer} [key] - SSL private key
 * @property {Buffer} [cert] - SSL certificate
 */

/**
 * Vinyl file object interface
 * @typedef {object} VinylFile
 * @property {string} path - File path
 */

Error Handling

  • Server Not Running: livereload.changed() and livereload.reload() will silently do nothing if no server is listening
  • Invalid File Paths: Objects passed to livereload.changed() must have a path property or the call will be ignored
  • Server Already Running: livereload.listen() will exit immediately if a server is already running
  • HTTPS Errors: Invalid SSL key/cert configuration will cause server startup to fail

Debug Logging

Enable debug logging by setting the DEBUG environment variable:

DEBUG=gulp:livereload gulp watch

This will show detailed information about server startup, file change notifications, and reload events.