README.md

grunt-connect-rewrite v0.2.1

This plugin provides RewriteRules middleware for the Grunt Connect / Express. Which could be used to redirect (rewrite internally or redirect using HTTP codes) User to the specific URL based on RegExp Rules.

More flexible alternative

In case you like this plugin it makes sense to look at http-rewrite-middleware as more flexible alternative.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-connect-rewrite --save-dev

Options

Rule's format:

{from: '__from__', to: '__to__'[, redirect: 'permanent'|'temporary']}

Where:

• __from__ - RegExp string to match.
• __to__ - String that replaces matched URL.
• redirect - Optional parameter:
  • When it is omitted then the Rule will be dispatched as an internal rewrite (aka proxified).
  • If the value is set then Browser will receive HTTP Location Header with value of parsed __to__ (permanent value will give HTTP 301, any other value will give HTTP 302).

rulesProvider

Type: String

Default value: connect.rules

You can specify grunt config section from which Rules will be read, like so:

grunt.initConfig({
    express: {
        options: {
            port: 9000
        },
        server: {
            hostname: 'localhost'
        },
        rules: [
            // ... your rules here
        ]
    },
    configureRewriteRules: {
        options: {
            rulesProvider: 'express.rules'
        }
    }
})

Example of usage

In your project's Gruntfile:

• Include the rewriteRequest snippet.
• Add a section named rules to your existing Connect or Express definition. Please note: unlike options, rules cannot be set per server, so the rules attribute must always be nested directly under connect or express.
• Add configureRewriteRules before the web server task.
• Don't forget to load the plugin (e.g. grunt.loadNpmTasks('grunt-connect-rewrite')).

var rewriteRulesSnippet = require('grunt-connect-rewrite/lib/utils').rewriteRequest;
grunt.initConfig({
    connect: {
        options: {
            port: 9000,
            hostname: 'localhost'
        },
        rules: [
            // Internal rewrite
            {from: '^/index_dev.html$', to: '/src/index.html'},
            // Internal rewrite
            {from: '^/js/(.*)$', to: '/src/js/$1'},
            // 301 Redirect
            {from: '^/old-stuff/(.*)$', to: '/new-cool-stuff/$1', redirect: 'permanent'},
            // 302 Redirect
            {from: '^/stuff/(.*)$', to: '/temporary-stuff/$1', redirect: 'temporary'}
        ],
        development: {
            options: {
                middleware: function (connect, options) {
                    var middlewares = [];

                    // RewriteRules support
                    middlewares.push(rewriteRulesSnippet);

                    if (!Array.isArray(options.base)) {
                        options.base = [options.base];
                    }

                    var directory = options.directory || options.base[options.base.length - 1];
                    options.base.forEach(function (base) {
                        // Serve static files.
                        middlewares.push(connect.static(base));
                    });

                    // Make directory browse-able.
                    middlewares.push(connect.directory(directory));

                    return middlewares;
                }
            }
        }
    }
})

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

// "configureRewriteRules" should be before the "connect"/"express" task
grunt.registerTask('server', function (target) {
    grunt.task.run([
        'configureRewriteRules',
        'connect:development'
    ]);
});

Debugging rules

In order to debug Rules you need to run grunt with a --verbose command-line option this will enable logging of matched rules. The message will explain which __from__ rule was matched and what was the result of the rewrite.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 2014.01.29 v0.2.1 Add logging support
• 2013.11.21 v0.2.0 Add support for Browser's redirects (HTTP 301/302)
• 2013.07.27 v0.1.1 Add possibility to read settings from custom grunt config path
• 2013.04.12 v0.1.0 Initial Release