grunt-connect-proxy

0.2.0 verified Sat Apr 25 auth: no javascript maintenance

Grunt plugin providing an HTTP proxy middleware for grunt-contrib-connect. Current stable version is 0.2.0 (last release circa 2015, maintenance mode). It allows developers to proxy requests from a local Connect server to remote hosts during development, supporting context path mapping, HTTPS, custom headers, and header hiding. Unlike general-purpose proxies, it integrates directly into Grunt's connect task middleware chain. Requires Grunt ~0.4.1 and is Node >= 0.10.0 compatible. No significant updates since 2015; consider alternatives like http-proxy-middleware for modern projects.

Common errors

error Warning: Task "configureProxies" not found. ↓

cause Missing grunt.loadNpmTasks('grunt-connect-proxy') in Gruntfile.

fix

Add grunt.loadNpmTasks('grunt-connect-proxy'); at the top of your Gruntfile.

error TypeError: Cannot read property 'proxyRequest' of undefined ↓

cause Incorrect require path; trying to import from main module instead of lib/utils.

fix

Use require('grunt-connect-proxy/lib/utils').proxyRequest

error Proxy not working, requests bypass middleware ↓

cause Proxy middleware added after static file middleware in the array.

fix

Ensure proxy is the first middleware in the array: [proxy, ...]

error configureProxies:server ran but no proxies active ↓

cause Target name mismatch or proxies object not inside the correct connect target.

fix

Verify proxies array is inside options of the connect target (e.g., connect.server.options.proxies).

Warnings

gotcha The configureProxies task must specify the connect target (e.g., configureProxies:server) or proxies will not be applied. ↓

fix Always pass the target name to configureProxies, e.g., 'configureProxies:server'.

gotcha The middleware function must include the proxy before static files, otherwise requests to proxied paths will be served statically first. ↓

fix Ensure proxy middleware is first in the middlewares array.

gotcha Calling require('grunt-connect-proxy') returns an object, not the proxy function. The proxyRequest function is in lib/utils. ↓

fix Use require('grunt-connect-proxy/lib/utils').proxyRequest.

deprecated Package is unmaintained since 2015; no updates for Node versions beyond 0.12 or Grunt 1.x compatibility. ↓

fix Migrate to modern alternatives like http-proxy-middleware with grunt-contrib-connect or standalone.

Install

npm install grunt-connect-proxy

yarn add grunt-connect-proxy

pnpm add grunt-connect-proxy

Imports

grunt-connect-proxy
wrong
```
require('grunt-connect-proxy');
```
correct
```
grunt.loadNpmTasks('grunt-connect-proxy');
```
Grunt plugins are loaded via loadNpmTasks in Gruntfile, not direct require.

proxyRequest

wrong

var proxy = require('grunt-connect-proxy').proxyRequest;

correct

var proxy = require('grunt-connect-proxy/lib/utils').proxyRequest;

The proxyRequest function is exported from lib/utils, not the main module.

configureProxies
```
grunt.registerTask('server', ['configureProxies:server', 'connect:server']);
```
configureProxies is a task registered by the plugin, not a function you import.

Quickstart

Shows complete Gruntfile setup: loading plugin, configuring connect with proxy middleware, adding proxy context, and registering server task.

// Gruntfile.js
module.exports = function(grunt) {
  grunt.loadNpmTasks('grunt-connect-proxy');
  grunt.initConfig({
    connect: {
      server: {
        options: {
          port: 9000,
          hostname: 'localhost',
          middleware: function(connect, options) {
            var proxy = require('grunt-connect-proxy/lib/utils').proxyRequest;
            return [proxy, connect.static(options.base)];
          }
        },
        proxies: [
          {
            context: '/api',
            host: 'api.example.com',
            port: 80
          }
        ]
      }
    }
  });
  grunt.registerTask('server', ['configureProxies:server', 'connect:server']);
};