nginx | Apache HTTPD | Lighttpd | express.js | koa.js | Caddy | Customization

Simple HttpErrorPages

Simple HTTP Error Page Generator. Create a bunch of custom error pages - suitable to use with Lighttpd, Nginx, expressjs, koajs ,Apache-Httpd or any other Webserver.

Features

• Static pages (for webservers)
• Multi-Language (i18n) support
• Generator script to customize pages
• Native express.js middleware
• Native koa.js middleware

Demo

• HTTP400
• HTTP401
• HTTP403
• HTTP404
• HTTP500
• HTTP501
• HTTP502
• HTTP503
• HTTP520
• HTTP521

Download

Just clone/download the git repository or use the prebuild packages (only the generated html files are included)

Download Prebuild Packages (Pages only, en_US)

• Download Single Files

NGINX Integration

NGINX supports custom error-pages using multiple error_page directives.

File: default.conf

Example - assumes HttpErrorPages are located into /var/ErrorPages/.

server {
    listen      80;
    server_name localhost;
    root        /var/www;
    index       index.html;
    
    location / {
        try_files $uri $uri/ =404;
        
        # add one directive for each http status code
        error_page 400 /ErrorPages/HTTP400.html;
        error_page 401 /ErrorPages/HTTP401.html;
        error_page 402 /ErrorPages/HTTP402.html;
        error_page 403 /ErrorPages/HTTP403.html;
        error_page 404 /ErrorPages/HTTP404.html;
        error_page 500 /ErrorPages/HTTP500.html;
        error_page 501 /ErrorPages/HTTP501.html;
        error_page 502 /ErrorPages/HTTP502.html;
        error_page 503 /ErrorPages/HTTP503.html;
    }

    # redirect the virtual ErrorPages path the real path
    location /ErrorPages/ {
        alias /var/ErrorPages/;
        internal;
    }

Apache Httpd Integration

Apache Httpd 2.x supports custom error-pages using multiple ErrorDocument directives.

File: httpd.conf or .htaccess

Example - assumes HttpErrorPages are located into your document root /var/www/...docroot../ErrorPages.

ErrorDocument 400 /ErrorPages/HTTP400.html
ErrorDocument 401 /ErrorPages/HTTP401.html
ErrorDocument 403 /ErrorPages/HTTP403.html
ErrorDocument 404 /ErrorPages/HTTP404.html
ErrorDocument 500 /ErrorPages/HTTP500.html
ErrorDocument 501 /ErrorPages/HTTP501.html
ErrorDocument 502 /ErrorPages/HTTP502.html
ErrorDocument 503 /ErrorPages/HTTP503.html

Lighttpd Integration

Lighttpd supports custom error-pages using the server.errorfile-prefix directive.

File: lighttpd.conf

Example - assumes HttpErrorPages are located into /var/www/ErrorPages/.

server.errorfile-prefix = "/var/www/ErrorPages/HTTP"

expressjs Integration

HttpErrorPages are available as NPM-Package - just install http-error-pages via npm/yarn

Installation

yarn add http-error-pages

Example

A ready-to-use example can be found in examples/express.js

const _express = require('express');
const _webapp = _express();
const _httpErrorPages = require('http-error-pages');

async function bootstrap(){
    // demo handler
    _webapp.get('/', function(req, res){
        res.type('.txt').send('HttpErrorPages Demo');
    });

    // throw an 403 error
    _webapp.get('/my403error', function(req, res, next){
        const myError = new Error();
        myError.status = 403;
        next(myError);
    });

    // throw an internal error
    _webapp.get('/500', function(req, res){
        throw new Error('Server Error');
    });

    // use http error pages handler (final statement!)
    // because of the asynchronous file-loaders, wait until it has been executed
    await _httpErrorPages.express(_webapp, {
        lang: 'en_US',
        payload: {
            footer: 'Hello <strong>World</strong>',
            myvar: 'hello world'
        }
    });

    // start service
    _webapp.listen(8888);
}

// invoke bootstrap operation
bootstrap()
    .then(function(){
        console.log('Running Demo on Port 8888');
    })
    .catch(function(e){
        console.error(e);
    });

Options

Syntax: Promise _httpErrorPages.express(expressWebapp [, options:Object])

• template (type:string) - the path to a custom EJS template used to generate the pages. default assets/template.ejs
• css (type:string) - the path to a precompiled CSS file injected into the page. default assets/layout.css
• lang (type:string) - language definition which should be used (available in the i18n/ directory). default en_US
• payload (type:object) - additional variables available within the template
• payload.footer (type:string) - optional page footer content (html allowed). default null
• filter (type:function) - filter callback to manipulate the variables before populated within the template
• onError (type:function) - simple debug handler to print errors to the console (not to be used in production!)

koajs Integration

HttpErrorPages are available as NPM-Package - just install http-error-pages via npm/yarn

Installation

yarn add http-error-pages

Example

A ready-to-use example can be found in examples/koa.js. Keep in mind that the following example has to be executed within an async context!

const _koa = require('koa');
const _webapp = new _koa();
const _httpErrorPages = require('http-error-pages');

// use http error pages handler (INITIAL statement!)
// because of the asynchronous file-loaders, wait until it has been executed - it returns an async handler
_webapp.use(await _httpErrorPages.koa({
    lang: 'en_US',
    payload: {
        footer: 'Hello <strong>World</strong>',
        myvar: 'hello world'
    }
    
}));

// add other middleware handlers
_webapp.use(async (ctx, next) => {
    if (ctx.path == '/'){
        ctx.type = 'text';
        ctx.body = 'HttpErrorPages Demo';
    }else{
        return next();
    }
});

// start service
_webapp.listen(8888);

Options

Syntax: Promise _httpErrorPages.koa([options:Object])

• template (type:string) - the path to a custom EJS template used to generate the pages. default assets/template.ejs
• css (type:string) - the path to a precompiled CSS file injected into the page. default assets/layout.css
• lang (type:string) - language definition which should be used (available in the i18n/ directory). default en_US
• payload (type:object) - additional variables available within the template
• payload.footer (type:string) - optional page footer content (html allowed). default null
• filter (type:function) - filter callback to manipulate the variables before populated within the template
• onError (type:function) - simple debug handler to print errors to the console (not to be used in production!)

Caddy Integration

Caddy supports custom error-pages using errors directive.

File: Caddyfile

Example - assumes HttpErrorPages are located into /var/www/error.

www.yoursite.com {
    
    // Other configurations

    errors {
        404 /var/www/error/HTTP404.html
    }

    // Other configurations

}

Customization

First of all, clone or download the http-error-pages repository.

Install Dependencies

You have to install the node dev dependencies to build the pages:

# run the yarn command within the cloned repository
yarn install

# or if you more familiar with npm..
npm install

To customize the pages, you can edit any of the template files and finally run the generator-script. All generated html files are located into the dist/ directory by default.

If you wan't to add custom pages/additional error-codes, just put a new entry into the i18n/pages-en_US.json file (its recommended to copy the file). The generator-script will process each entry and generates an own page.

Files

• config.json - basic configuration options
• assets/layout.scss - the SCSS based styles
• assets/template.ejs - the EJS based page template
• i18n/pages-.json - the page definitions (multilanguage)
• dist/*.html - generator output directory

Change page styles

To modify the page styles, just edit the SCSS based layout assets/layout.scss and finally run gulp to generate the css code. The new layout file is stored in assets/layout.css - run the page generator to create the pages.

Example

# start gulp sccs via npm
$ npm run gulp

> [email protected] gulp HttpErrorPages
> gulp

[08:40:33] Using gulpfile HttpErrorPages/gulpfile.js
[08:40:33] Starting 'sass'...
[08:40:34] Finished 'sass' after 108 ms
[08:40:34] Starting 'default'...
[08:40:34] Finished 'default' after 40 μs

# generate http-error-pages using modified stylesheet
$ npm run static

> [email protected] static HttpErrorPages
> node bin/generator.js static

Paths
 |- Config: HttpErrorPages/config.json
 |- Template: HttpErrorPages/assets/template.ejs
 |- Styles: HttpErrorPages/assets/layout.css
 |- Pages: HttpErrorPages/i18n/pages-en_US.json

Generating static pages
 |- Page <HTTP404.html>
 |- Page <HTTP403.html>
 |- Page <HTTP400.html>
 |- Page <HTTP500.html>
 |- Page <HTTP501.html>
 |- Page <HTTP502.html>
 |- Page <HTTP520.html>
 |- Page <HTTP503.html>
 |- Page <HTTP521.html>
 |- Page <HTTP533.html>
 |- Page <HTTP401.html>
Static files generated

Multi language (i18n)

To use a different language just provide a custom page definition - in case the file is located in i18n you can use the --lang option

Example

$ npm run static -- --lang pt_BR

> [email protected] static HttpErrorPages
> node bin/generator.js static "--lang" "pt_BR"

Paths
 |- Config: HttpErrorPages/config.json
 |- Template: HttpErrorPages/assets/template.ejs
 |- Styles: HttpErrorPages/assets/layout.css
 |- Pages: HttpErrorPages/i18n/pages-pt_BR.json

Generating static pages
 |- Page <HTTP404.html>
 |- Page <HTTP400.html>
 |- Page <HTTP401.html>
 |- Page <HTTP403.html>
 |- Page <HTTP500.html>
 |- Page <HTTP501.html>
 |- Page <HTTP502.html>
 |- Page <HTTP520.html>
 |- Page <HTTP503.html>
 |- Page <HTTP521.html>
 |- Page <HTTP533.html>
Static files generated

Add custom pages

Create custom error codes/pages used by e.g. CloudFlare

Example

// webserver origin error
"520": {
    "title": "Origin Error - Unknown Host",
    "message": "The requested hostname is not routed. Use only hostnames to access resources."
},

// webserver down error
"521": {
    "title": "Webservice currently unavailable",
    "message": "We've got some trouble with our backend upstream cluster.\nOur service team has been dispatched to bring it back online."
},

Change footer message

The footer message can easily be changed/removed by editing config.json.

Example - customm footer

{
    //  Output Filename Scheme - eg. HTTP500.html
    "scheme": "HTTP%code%.html",

    // Footer content (HTML Allowed)
    "footer": "Contact <a href=\"mailto:[email protected]\">[email protected]</a>"
}

Example - no footer

{
    //  Output Filename Scheme - eg. HTTP500.html
    "scheme": "HTTP%code%.html"
}

Placeholders/Variables

The following set of variables is exposed to the ejs template (404 page example):

{
  title: 'Resource not found',
  message: 'The requested resource could not be found but may be available again in the future.',
  code: '404',
  language: 'en',
  scheme: 'HTTP%code%.html',
  pagetitle: "We've got some trouble | %code% - %title%",
  footer: 'Tech Contact <a href="mailto:[email protected]">[email protected]</a>',
  myvar: 'Hello World'
}

To generate dynamic titles/content based on the current variable set, each variable is exposed as placeholder (surrounded by %).

You can also define custom variable within the page definitions, everything is merged togehter.

Modify the HTML template

The HTML template is based on ejs and located in assets/template.ejs - you can apply any kind of changes.

<!DOCTYPE html>
<html lang="<%= vars.language %>">
<head>
    <!-- Simple HttpErrorPages | MIT License | https://github.com/HttpErrorPages -->
    <meta charset="utf-8" /><meta http-equiv="X-UA-Compatible" content="IE=edge" /><meta name="viewport" content="width=device-width, initial-scale=1" />
    <title><%= vars.pagetitle %></title>
    <style type="text/css"><%- vars.inlinecss %></style>
</head>
<body>
    <div class="cover"><h1><%= vars.title %> <small><%= vars.code %></small></h1><p class="lead"><%= vars.message %></p></div>
    <% if (vars.footer){ %><footer><p><%- vars.footer %></p></footer><% } %>
</body>
</html>

Command line options

The http-error-pages generator allows you to use custom template/config files directly. This is the recommended method to create full-customized pages.

$ npm run static -- --help

> [email protected] static HttpErrorPages
> node bin/generator.js static "--help"

  Usage: static [options] [config]

  run http-error-pages generator

  Options:

    -t, --template <path>  path to your custom EJS template file
    -s, --styles <path>    path to your custom stylesheet (precompiled as CSS!)
    -p, --pages <path>     path to your custom page definition
    -l, --lang <lang>      the language of the default page definition
    -o, --out <path>       output directory
    -h, --help             output usage information

Example - use custom files

We assume you've created a folder named example_org which contains all relevant template files

# via npm run-script (cross platform)
$ npm run static -- -t example_org/template.ejs -s example_org/styles.css -p example_org/pages.json -o example_org/output

# .. or directly (linux only)
$ http-error-pages -t example_org/template.ejs -s example_org/styles.css -p example_org/pages.json -o example_org/output

License

HttpErrorsPages is OpenSource and licensed under the Terms of The MIT License (X11) - your're welcome to contribute