[ Impressum ]


www.Rozek.de > Node.js > SimpleCGI
SimpleCGI is a simple Express.js [1] "Middleware" for connecting a CGI processor with an HTTP server built using Node.js [2]. It was originally developed for the "LiveCode Server"[3] package, but may also used together with other CGI/1.1-compatible programs.

This page describes installation and use of the SimpleCGI module.


  • Download and Installation of SimpleCGI
  • Using SimpleCGI
  • automated Tests

Download and Installation of SimpleCGI

Installation of SimpleCGI is quite simple:
  1. If not already done, install Node.js on your computer;
  2. change to the (possibly newly created) directory in which you want to set up your Express.js server;
  3. install SimpleCGI using
    npm install simplecgi
Thereafter SimpleCGI is ready for use.

Using SimpleCGI

SimpleCGI is an Express.js "middleware" and therefore used as such. At the beginning, you should attach SimpleCGI once using:

var SimpleCGI = require('simplecgi');

You can then route incoming HTTP requests to SimpleCGI within your Express.js app:

app.all(RoutingRule, SimpleCGI(CGIProcessor, CGIBaseFolder, RoutingRule));

The variables mentioned therein have the following meaning:
  • RoutingRule
    contains the rule, which Express.js applies to the URL of an incoming HTTP request in order to recognize it as a CGI request and forward it to SimpleCGI. SimpleCGI needs this rule itself, to identify any additional information behind the reference to the invoked CGI script;
  • CGIProcessor
    contains the path to the program, which actually processes any CGI requests;
  • CGIBaseFolder
    contains the directory, within which the executing CGI script can be found.
A concrete example should clarify this:

var express = require('express'); var SimpleCGI = require('simplecgi');

var WebServer = express();
WebServer.all(/^.+[.]sh/, SimpleCGI(
__dirname + '/CGIProcessor.sh', __dirname + '/www', /^.*[.]sh/

This little script will start an HTTP server on port 8100 with the following properties:
  • requests with an "sh." in the URL (such as "") are forwarded to SimpleCGI - all other requests will be ignored;
  • the requests are processed by a shell script (this might be unusual, but is still quite possible - especially for testing purposes);
  • this shell script (called "CGIProcessor.sh") is located in the same directory as the Express.js server;
  • the CGI script which is to be executed by the CGIProcessor is searched in subdirectory "/www" of the directory containing the Express.js server (in this particular case, SimpleCGI would look for "./www/example/test.sh").
    It is quite normal that CGI scripts are located in the same directories as other (static) files - it is not, however, absolutely necessary.
SimpleCGI defines all common CGI/1.1 environment variables:


Without any output from the CGI processor, SimpleCGI responds with a status code of 204 (No Content).

If the CGI processor output does not start with lines that can be recognized as HTTP headers, SimpleCGI sets the Content-Type to Application/Octet-Stream. Anyway, SimpleCGI never applies any character or line-end conversions, but forwards all output to the requesting client unmodified - thus, SimpleCGI may also be used for binary data.

Error messages from the CGI processor and exit codes > 0 are only logged on the (server) console, but have no effect on status code or content of an HTTP response. It is the responsibility of the CGI processor itself, to report back any errors in an appropriate manner to the client.

Automated Tests

SimpleCGI can be tested automatically. The tests are part of the SimpleCGI package and installed together with it. You will, however, have to additionally install the Mocha[4] package in order to run these tests:

npm install -g mocha

A "global" installation of Mocha (by specifying -g) is not absolutely necessary, but it simplifies the invocation of tests, because the path to Mocha itself does not have to be specified any more.

As usual with Mocha, the test scripts are not started directly, but from within Mocha itself:

mocha -u tdd <SimpleCGI-Installation-Folder>/simplecgi-tests.js

In this command, "<SimpleCGI-Installation-Folder>" represents the installation folder of SimpleCGI (within a node_modules directory). If everything works properly, you should see the following output:

â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â?â? â?â?â?â?â?â?â?â?â?â?

49 passing (356ms)

Have fun with SimpleCGI! Creative Commons License


Tj Holowaychuk
Express - node.js web application framework
Express is a lightweight web application framework for Node.js. Thanks to its modularity, Express allows for rapid development of HTTP servers based on Node.js.
Joyent Inc.
Node.js is first and foremost a platform for extremely powerful network applications written in JavaScript. However, in combination with other technologies (such as Node-WebKit) Node.js may also be used for more than just HTTP servers.
(RunRev Ltd.)
LiveCode | LiveCode Server Guide
The LiveCode Server is an interpreter for LiveCode scripts that is started from the command line (does not offer any graphical user interface) and is intended primarily as a CGI processor (this way, web pages can be processed with LiveCode - thus, you do not necessarily have to learn PHP any longer).
TJ Holowaychuk
Mocha - the fun, simple, flexible JavaScript test framework
Mocha is an easy-to-use framework for synchronous and asynchronous tests running under Node.js or within a browser.