or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-gulp-connect

Gulp plugin to run a webserver with LiveReload functionality

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

To install, run

npx @tessl/cli install tessl/npm-gulp-connect@5.7.0

index.mddocs/

gulp-connect

gulp-connect is a Gulp plugin that provides a development web server with LiveReload functionality. It enables developers to serve static files during development with automatic browser refresh capabilities when files change, supporting multiple server instances, HTTPS/HTTP2, custom middleware integration, and flexible configuration options. The package is written in CoffeeScript and compiled to JavaScript during the build process.

Package Information

  • Package Name: gulp-connect
  • Package Type: npm
  • Language: JavaScript (compiled from CoffeeScript source)
  • Installation: npm install --save-dev gulp-connect

Core Imports

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

Basic Usage

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

// Basic server
gulp.task('connect', function() {
  connect.server();
});

// Server with LiveReload
gulp.task('connect', function() {
  connect.server({
    root: 'app',
    livereload: true
  });
});

// Watch and reload files
gulp.task('html', function () {
  return gulp.src('./app/*.html')
    .pipe(gulp.dest('./app'))
    .pipe(connect.reload());
});

gulp.task('default', gulp.series('connect', 'html'));

Capabilities

Server Creation

Creates and starts a Connect-based web server with optional LiveReload support.

/**
 * Creates and starts a Connect-based web server
 * @param {Object} options - Server configuration options
 * @param {Function} startedCallback - Optional callback executed when server starts
 * @returns {ConnectApp} ConnectApp instance
 */
connect.server(options?, startedCallback?);

Options:

interface ServerOptions {
  /** Server name for logging (default: "Server") */
  name?: string;
  /** Server port (default: 8080) */
  port?: number;
  /** Server hostname (default: "localhost") */
  host?: string;
  /** Document root directory/directories (default: directory with gulpfile) */
  root?: string | string[];
  /** Enable HTTPS with optional configuration (default: false) */
  https?: boolean | HttpsOptions;
  /** Force HTTP/1.1 over HTTP/2 (default: false) */
  preferHttp1?: boolean;
  /** Enable LiveReload functionality (default: false) */
  livereload?: boolean | LiveReloadOptions;
  /** Custom Connect middleware function */
  middleware?: (connect: any, opt: ServerOptions) => any[];
  /** Server initialization callback */
  serverInit?: (server: any) => void;
  /** Fallback file for SPA routing */
  fallback?: string | ((req: any, res: any) => string);
  /** Index file configuration (default: true) */
  index?: boolean | string | string[];
  /** Enable debug logging (default: false) */
  debug?: boolean;
  /** Suppress all logging (default: false) */
  silent?: boolean;
}

interface HttpsOptions {
  key?: Buffer | string;
  cert?: Buffer | string;
  ca?: Buffer | string;
  passphrase?: string;
  [key: string]: any;
}

interface LiveReloadOptions {
  /** LiveReload server port (default: 35729) */
  port?: number;
  /** Overrides the hostname of the script livereload injects in index.html */
  hostname?: string;
}

Usage Examples:

// Basic server
connect.server();

// Custom configuration
connect.server({
  name: 'Dev Server',
  port: 9000,
  root: ['app', 'dist'],
  livereload: true,
  https: true
});

// Multiple servers
connect.server({
  name: 'Dev App',
  root: 'app',
  port: 8000,
  livereload: true
});

connect.server({
  name: 'Dist App', 
  root: 'dist',
  port: 8001,
  livereload: true
});

// With custom middleware
connect.server({
  root: 'app',
  middleware: function(connect, opt) {
    return [
      // Custom middleware stack
    ];
  }
});

// With callback
connect.server({
  port: 8080
}, function() {
  console.log('Server started!');
});

// With dynamic fallback function
connect.server({
  root: 'app',
  fallback: function(req, res) {
    // Custom logic to determine fallback path
    if (req.url.startsWith('/api/')) {
      return 'api-fallback.html';
    }
    return 'index.html';
  }
});

LiveReload Stream

Returns a Gulp stream that triggers LiveReload for connected browsers when files change.

/**
 * Returns a Gulp stream that triggers LiveReload for connected browsers
 * @returns {Transform} Transform stream that triggers LiveReload on file changes
 */
connect.reload();

Usage Examples:

// Trigger reload after processing files
gulp.task('html', function () {
  return gulp.src('./app/*.html')
    .pipe(gulp.dest('./app'))
    .pipe(connect.reload());
});

// Multiple file types
gulp.task('assets', function () {
  return gulp.src('./app/assets/**/*')
    .pipe(gulp.dest('./dist/assets'))
    .pipe(connect.reload());
});

// In watch tasks
gulp.task('watch', function () {
  gulp.watch(['./app/*.html'], gulp.series('html'));
  gulp.watch(['./app/css/*.css'], function() {
    return gulp.src('./app/css/*.css')
      .pipe(connect.reload());
  });
});

Server Shutdown

Stops all running Connect servers and clears the server registry.

/**
 * Stops all running Connect servers and clears the server registry
 * @returns {void}
 */
connect.serverClose();

Usage Examples:

// Clean shutdown after tests
gulp.task('test', function(done) {
  connect.server({
    port: 8888
  });
  
  // Run tests...
  
  // Clean up
  connect.serverClose();
  done();
});

// Programmatic control
function startDevelopment() {
  connect.server({
    root: 'app',
    livereload: true
  });
}

function stopDevelopment() {
  connect.serverClose();
}

Server Features

  • Multiple Servers: Support for running multiple server instances simultaneously with different configurations
  • HTTPS Support: Built-in SSL/TLS with default certificates or custom configuration
  • HTTP/2 Support: Automatic HTTP/2 when using HTTPS if the http2 npm package is installed (configurable via preferHttp1)
  • LiveReload: Real-time browser refresh on file changes with configurable port
  • Custom Middleware: Extensible middleware chain via options.middleware
  • SPA Support: Fallback routing for single-page applications via options.fallback
  • Debug Mode: Detailed connection and request logging via options.debug
  • Flexible Root: Single directory or array of directories for serving files
  • Index Configuration: Configurable index file handling

Error Handling

  • Server startup errors are logged and handled gracefully
  • Invalid configurations result in warning messages
  • Graceful shutdown on process signals (SIGINT, exit)
  • Socket connection tracking for clean server termination
  • LiveReload server errors are suppressed to prevent noise

Types

class ConnectApp {
  constructor(options: ServerOptions, startedCallback?: Function);
  
  /** Current server state */
  state: "initializing" | "starting" | "running" | "stopped";
  
  /** Stop the server instance */
  close(): void;
  
  /** Server configuration properties */
  name: string;
  port: number;
  host: string;
  root: string | string[];
  https: boolean | HttpsOptions;
  livereload: boolean | LiveReloadOptions;
  
  /** Internal server instances */
  server: any;
  lr: any;
  app: any;
  sockets: any[];
}