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
-
Create a folder
mkdir my-saco-launcher
andcd
into it. -
Start new npm project with
npm init -y
and drag your single page web app files inside. -
npm i --save saco
-
Create a script such as:
const path = ;const Saco = ; rootPath: path start;
- 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:
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.