Grunt Connect Web Server

Common errors

• Fatal error: Port 9000 is already in use by another process.

  cause The specified port in the `connect` task configuration is already occupied by another application or process on your system.
  fix Change the `port` option in your Gruntfile's `connect` task to an unused port, or enable `useAvailablePort: true` (if supported and desired) to automatically find a free port.

• Warning: Task "connect" not found. Use --force to continue.

  cause The `grunt-contrib-connect` plugin has not been loaded correctly in your Gruntfile, or it's not installed.
  fix Ensure you have `npm install grunt-contrib-connect --save-dev` and `grunt.loadNpmTasks('grunt-contrib-connect');` in your Gruntfile.

• Error: listen EADDRINUSE: address already in use :::8000

  cause This is a low-level Node.js error indicating that the server tried to bind to a network address and port that is already in use by another process.
  fix This typically means another server is running on the same port. Use `lsof -i :8000` (macOS/Linux) or `netstat -ano | findstr :8000` (Windows) to identify and terminate the conflicting process, or change the port in your Gruntfile.

Warnings

• breaking Version 5.0.0 replaced `node-http2` with `http2-wrapper`. If your Gruntfile had custom configurations or relied on specific behaviors of the previous HTTP/2 implementation, this change might introduce breaking changes. Review HTTP/2 related options and ensure compatibility.
  Fix: Review your `protocol: 'http2'` configurations. Test your HTTP/2 endpoints thoroughly after upgrading to v5.x. Consult the `http2-wrapper` documentation if you encounter issues.
• gotcha Using the `keepalive: true` option will prevent any subsequent Grunt tasks from running, as the server will remain active indefinitely. This is intended behavior for long-running servers but can be a common pitfall.
  Fix: Only use `keepalive: true` for dedicated server tasks (e.g., `grunt serve`). For development workflows where other tasks need to run (e.g., `watch`), either omit `keepalive` or run `connect` in a separate `grunt-concurrent` task if you need it alongside other blocking tasks.
• gotcha When `hostname` is set to a wildcard like `'0.0.0.0'`, the `open` option will default to using `localhost` in the browser URL. If you need a specific IP or hostname opened, explicitly set the `open` option to a full URL (e.g., `open: 'http://192.168.1.100:9000'`).
  Fix: If `hostname` is a wildcard and `open: true`, specify the full URL in the `open` option to override the default `localhost` behavior (e.g., `open: 'http://<your-ip>:<port>'`).
• gotcha Attempting to use `protocol: 'http2'` may lead to browser compatibility issues if the client browser does not fully support HTTP/2 or the specific server configuration. Ensure your client environment is up-to-date.
  Fix: Test your application with various browsers when using HTTP/2. If issues arise, consider reverting to `protocol: 'http'` or `https` for broader compatibility or for debugging purposes.

Install

• npm install grunt-contrib-connect npm
• yarn add grunt-contrib-connect yarn
• pnpm add grunt-contrib-connect pnpm

Imports

• connect
  wrong:

  import { connect } from 'grunt-contrib-connect';
  const connect = require('grunt-contrib-connect');

  correct:

  grunt.loadNpmTasks('grunt-contrib-connect');

  Grunt plugins are loaded via `grunt.loadNpmTasks` in the Gruntfile, not directly imported or required into application code.
• Task Configuration
  wrong:

  grunt.config.set('connect', { /* ... */ });

  correct:

  grunt.initConfig({
    connect: {
      // options here
    }
  });

  Configuration for `grunt-contrib-connect` is typically nested under the `connect` key within `grunt.initConfig()`. While `grunt.config.set` works, `initConfig` is the standard approach for initial setup.

Quickstart

This quickstart demonstrates how to install `grunt-contrib-connect`, load it in your Gruntfile, and configure two `connect` tasks: one for development with live reload and automatic browser opening, and another for testing that keeps the server alive indefinitely. It also shows a basic `grunt-contrib-watch` setup, a common companion to `connect` for modern web development workflows.

// Gruntfile.js
module.exports = function(grunt) {
  // Load the plugin that provides the 'connect' task.
  grunt.loadNpmTasks('grunt-contrib-connect');
  grunt.loadNpmTasks('grunt-contrib-watch'); // Often used alongside connect

  grunt.initConfig({
    connect: {
      options: {
        port: 9000,
        hostname: 'localhost', // '0.0.0.0' for external access
        livereload: 35729 // Set a specific port for live reload
      },
      dev: {
        options: {
          open: true, // Automatically open the browser
          base: 'app' // Serve files from the 'app' directory
        }
      },
      test: {
        options: {
          port: 9001,
          base: ['temp', 'test'], // Serve from multiple directories
          keepalive: true // Keep server alive for continuous testing
        }
      }
    },

    watch: {
      options: {
        livereload: '<%= connect.options.livereload %>'
      },
      files: [
        'app/**/*.{html,css,js}',
        '!app/vendor/**/*.js' // Ignore vendor files
      ],
      tasks: [] // No tasks, just trigger livereload
    }
  });

  // Register a default task that runs connect and watch
  grunt.registerTask('default', ['connect:dev', 'watch']);
  grunt.registerTask('serve-test', ['connect:test']);
};