Zerver is a lightweight Node.js-based webserver that lets you seamlessly make server API calls as if they were a library on the client. The goal is to provide a developer-focused toolset and remove all the boilerplate involved in serving a webapp.
Install
npm install -g zerver# or add zerver to your package.json dependencies and run npm install
Basic usage
Let's say you have a directory of this structure.
website-dir/index.html
website-dir/zerver/MyAPI.js
Everything in website-dir
will be served as static content except for code in zerver/
which will run on the server.
Only files on the topmost level of the zerver folder will be saved as api's i.e. files in subfolders under zerver will not be used unless they are specifically required in one of the main api files.
// in website-dir/zerver/MyAPI.js// this runs on the serverexports { console; // 'hi from client' ;};
<!-- in website-dir/index.html --><!-- this runs in the browser -->
# run the server zerver website-dir# go to http://localhost:5000/ to view the magic
What just happened?
MyAPI.logStuff
automatically serializes the arguments of the function call and makes an AJAX request to the server. The server runs the function in website-dir/zerver/MyAPI.js
and responds to the client in a similar way.
Any amount of arguments can be used in the function calls as long as they are JSON stringify-able (with the exception of the callback function).
Note: any server code in a subdirectory of website-dir/zerver
will not be available for import on the client allowing for libraries of private server functionality.
Require syntax
<!-- in website-dir/index.html -->
Zerver options
# General usage zerver [options] website-dir # run server on a different port zerver --port=8000 website-dir -r, --refresh# Any webpage being viewed that has a Zerver script on it (`website-dir/index.html`) # will automatically refresh when any of its code is edited. # You can edit code and immediately see feedback on how it effects your running webapp. -c, --cli# Creates a js shell to communicate with remote clients, press tab to enable. # Any code run in this shell will be run on the client. -V, --verbose# Enable verbose request logging -l, --less# Automatically compile less into css # Requires the less node module to work run: npm install less -p, --production# Enables production mode (caching, concat, minfiy, gzip, etc)
Command Line Interface
The command line interface (the cli
flag) allows you to communicate with the client during development
For example:
zerver -cli website-dir # Press tab to enable the cli >>># The following line will cause all clients listening to the server to refresh >>> # You can also log things from the client # The following line logs all the functions # that are available in 'MyAPI' >>> console.log;log: ["function1FromMyApi", "function2FromMyApi"]# Since anything that is logged on the client gets # sent to the server you can see the result right in the command line
Production mode
Passing the --production
flag on startup enables zervers production features.
Inlining files
Given the following link
Zerver will create a <style>
tag in place and place the css there instead, reducing the amount of requests to load files.
The same can be done with images inside the css file
//);
Gzip and minifying
Given the following files in your manifest.
# zerver:js/main.min.js js/cards.jsjs/app.jsjs/main.js# /zerver
And the following in your HTML file:
<!-- zerver:js/main.min.js --><!-- /zerver -->
When the server is run on production these files will be gzipped & minified into a file called main.min.js
Manifest file
Zerver has automatic support for HTML5 appcache manifests. This means that Zerver will automatically detect their presence and make sure that clients always update when files referenced in the manifest have changed. The cache manifest file is a simple text file that lists the resources the browser should cache for offline access. It should be referenced at the top of your html file like this:
...
The cache manifest allows you to specify which files the browser should cache and make available to offline users. Your app will load and work correctly, even if the user presses the refresh button while they're offline.
The advantage that Zerver brings with the cache manifest is that it will refresh the cache whenever files are changed. This fixes the main drawback of developing with a manifest as now you will always be working with the most up to date versions of the edited files.
Default options
You can specify default options in an environment variable, to avoid having to type them every time or having different setups for different environments in which the code will run
export ZERVER_FLAGS='-rlc'
Running as an npm script
Another way to save time when running zerver is to add your default run configurations to an npm script in your package.json
Sample package.json file for a zerver application
This setup allows you to simply enter npm start
to run the command zerver -rlc web
.
ExpressJS integration
Zerver integrates well with Express, providing the same functionality to any existing webapp.
// "app" is an ExpressJS app instancevar zerver = ;app;
Along with the rest of your Express app, Zerver scripts will be accessible the specified path (url/to/zerve/at
) for importing into your client-side code.
Node module
A convenient tool for testing and server-to-server integration is the NodeJS Zerver module.
var zerver = ; zerver;
Script names
Zerver scripts can be globalised on the client under whatever name you please. If you are afraid of object name collisions simply define the query argument name
for the script and it will be globalised as such.
<!-- in website-dir/index.html -->
Error handling
<!-- in website-dir/index.html -->