SuperGirl

Full configurable node web server for single page applications.
Intended for platforms like Heroku or similar.

It support lot out of the box:

• CORS
• 404 page not found
• helmet
• compression
• logging
• clustering
• merge app configuration with environment settings
• dynamic frontend configuration

Installation

Supergirl can be installed and used local

npm install supergirl --save

as well global

npm install supergirl -g

Configuration

Supergirl expect by default a configuration file 'supergirl.config.json' inside your project root folder. You can set a custom configuration path and file using --config argument.

supergirl --config ./config/serve.config.json

The minimum required configuration is

• name The app name is used for 404 template
• path Is the URL route path
• root Is the relative root of your application

"serve": {
    "name": "supergirl",
    "static": {
        "path": "/",
        "root": "./dist"
    }
}    

Logging

Bunyan is used for logging. More option will soon be added.

"serve": {
    "bunyan": {
        "name": "supergirl",
        "level": "info"
    }
}    

CORS

Using the default koa 2 cors middleware kcors, we can pass all options throw.

"serve": {
    "cors": {
        //kcors options
    }
}    

404 - Page not found or redirect

Settings to what will happen in the case when a route is not found. By default, a 404 page is displayed. This leads on Single Page Apps using HTML 5 use style URLs to 404 page, when user press a browser reload. To avoid this, a redirect to app root is the better behaviour.

To active a redirect just add the relative path to your application. In most cases this will be root "/". Use the template property when you customize your 404 page and change the path or/and name of the template.

"serve": {
    "pagenotfound": {
        "redirect": false,
        "template": "404.html"
    }
}    

Activate redirect

"serve": {
    "pagenotfound": {
        "redirect": "/"
    }
}    

404 Page Template The 404 page template is using the EJS HTML Template. You can your own 404 page. Set the custom template folder and the template path and name inside this folder. You can attach all supergirl configuration properties inside this template.

"serve": {
    "templates": {
        "customPath": "./templates",
    },
    "pagenotfound": {
        "template": "404templates/custom404.html"
    }
}    

Using on heroku

To enable supergirl with your app on heroku you need to install it and create a configuration file, described below.
You also need a Procfile for heroku describe how to start your app. Procfile

web: node --optimize_for_size --max_old_space_size=460 --gc_interval=100 node_modules/supergirl/lib/index.js

The options you use here depend on the requirements of your app. More information on Profile you will find on heroku.

Dynamic Frontend Configuration

Supergirl gives the possiblity to use dynamic configuration settings for your application. Simply add some settings to app section inside your supergirl.config.json configuration file.

"app": {
    "backendURI": "https://staging.myapp.com/api"
}

You receive your app settings with AJAX call on route /config

{
    "backendURI": "https://staging.myapp.com/api"
}

Well this is still not dynamic. But you now can override these settings with environment variables.

Simply set sg_app_backendURI="https://production.myapp.com/api" on your system and these will override the settings of supergirl.config.json configuration file.

The request /config return:

{
    "backendURI": "https://production.myapp.com/api"
}

This way you even can add new settings to requested configuration. Just set sg_app_emailkey="123456".

The request /config return:

{
    "backendURI": "https://production.myapp.com/api",
    "emailkey": "123456"
}

Todo

• Add unit tests
• Finish documentation
• Add https server for standalone serving, as docker