Saco

A pre customized, express server for single page web apps that aims to be production ready. Saco promotes separation of concerns, quality, best practices and testability when deploying front end single page web apps.

By using Saco

...you avoid the following common mistakes:

• using development servers in production
• poluting your front end project with extra dependencies
• having your front end app on the same server of your back end server
• using non nodejs solutions
• incomplete production configuration

and benefit from having:

• expressjs properly configured for production
• http && https static folder hosting
• high quality and tested code launching your production server
• beautifully bootstrapped cluster with stop and start methods
• favicon hosted with serve-favicon
• gzip with compression
• customizable logging with debug
• customizable format timestamps
• multi core server
• resource caching
• configured to work behind proxies

Demo

npm run http-demo, npm run https-demo or npm run cluster-https-demo

How to use

1. Create a folder mkdir my-saco-launcher and cd into it.

2. Start new npm project with npm init -y and drag your single page web app files inside.

3. npm i --save saco

4. Create a script such as:

const path = require("path");
const Saco = require("saco");
new Saco.Server({ rootPath: path.join(__dirname, "/dist") }).start();

5. Run it as: cross-env NODE_ENV=production DEBUG=saco:* node my-script.js.

Notice that we used cross-env to set the environment variables. You may use another method.

How does it work exactly?

Well... Take a look at the code, its not much.

Behind a proxy

If your saco instance is behind proxy such as nginx, in order to have the request ip properly shown in the console do not forget to set the option behindProxy to true.

This will configure our server to trust a proxy and behave as explained here.

If your reverse proxy is Nginx you can add this proxy_set_header X-Forwarded-For $remote_addr; in your .conf file.

This will allow redefining or appending fields to the request header passed to the proxied server.

Inside Docker

Inside docker you need to define ip as '0.0.0.0'.

Server API

constructor(options: ServerOptions)

// returnes a promise that resolves only after all workers
// have sent ClusterMessage.WORKER_LISTENING to the master
start(): Promise<number>

// returnes a promise that resolves only after all
// workers have send 'exit' event to the master
stop(): Promise<any>

Options

Saco server supports the following options:

Link to ServerOptions.ts.

Remember values with ? are optional.

In order to have an https server key and cert paths must be defined.

Workers has a default and maximum value equal to the number of cores of your processor.

| option | What it does | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | name | Just a string to easily identify the server in the log. | | port | Where the server is going to listen. | | ip | The address where the server will be. For most cases this should be either 'localhost or '0.0.0.0'. | | cors | Set to true if you want to allow cross origin requests. | | dateformat | String describing logs dateformat. Must be supported by dateformat npm package. | | verbose | Set to true if you want to have logs in the console. | | key | HTTPS key. | | cert | HTTPS certificate. | | workers | Number of forks. Default value depends on number of processor cores. | | maxAge | Specifies, in milliseconds, for how long should resources stay in client cache. | | behindProxy | Enables trust proxy header. | | rootPath | Specify the path where the resources will be in the server local hard drive. | | index | Expects an object with url and path. Path is the relative path from rootPath until the file and url is the default url used by the server. | | assets | Same as index but for the assets used by the page. | | favicon | Same as index but for favicon file. |

Linting

npm run lint

Testing

npm run test

Logging

Use DEBUG=saco:* npm run your-launcher.js to have the logs printed on your console.

Contributing

Contributions will be highly appreciated.

Feel free to open any issues on any related matter.

Recommended versions

• node : v8.11.2

• npm: 5.6.0

• typescript: 2.8.3

LICENSE

Code released under the MIT license.