README

VIO

An express "endware" that takes your feelings into consideration.

Conversation

Why VIO

VIO is a small piece of the greater thing. Rather than a framework, it's more like a light-weight implementation that takes how a maintainable site structure should be like into consideration.

Take the view matching rule as example, it's a balance of how you might wish to put and name view components during design time.

An actual example including suggested file structure would introduce extra build steps. Of course it would, as VIO is designed for real-world Node.js projects.

It could be something like this:

project
├───bld             # build path.
│   ├───api
│   │   └───routes
│   ├───page
│   │   ├───routes
│   │   └───views   # contains .hbs files with the same structure as in src.
│   ├───server
│   │       www.js  # entry file.
│   └───static
└───src             # source path.
    ├───api
    │   └───routes
    ├───page
    │   └───routes
    │       │   default.js
    │       └───user
    │               account.js
    │               default.js
    ├───server
    │   │   www.js
    │   ├───models
    │   └───modules
    └───static
        ├───default              # things of one page are in one place.
        │   │   default.hbs
        │   │   default.less
        │   └───images
        └───user
        │   sign-in.hbs
        │   sign-up.hbs
        ├───account
        │       account.hbs  # faster editor navigation with filename.
        └───default
            user.hbs

You may configure tasks using gulp or other tools.

VIO is developed in TypeScript. As it's using new ECMAScript features, you will need to use compiler or transpiler like TypeScript or Babel.

Features

Map routes and controllers based on file paths.
Support dynamic routes mapping and hot module replacement during development.
Return a promise with data to render the view.
Use ES7 decorators to specify route handlers.

Checkout wiki for examples.

Install

Install VIO.

yarn add vio
# or
npm install vio --save

Install a view engine (here we use handlebars with consolidate). And if you are using TypeScript, install related declarations as well.

yarn add handlebars consolidate
yarn add @types/express @types/consolidate --dev

Check out handlebars-layout if it seems to be something you would want.

Usage

The following example is in TypeScript. If you are using Babel, the import statements will slightly differ.

src/server.ts

import * as Path from 'path';

import * as express from 'express';
import {handlebars} from 'consolidate';
import {Router} from 'vio';

let app = express();

app.engine('hbs', handlebars);

let router = new Router(app, {
  routesRoot: Path.join(__dirname, 'routes'),
  viewsRoot: Path.join(__dirname, '../views'),
  viewsExtension: '.hbs',
});

app.listen(1337);

src/routes/default.ts

import {Controller, get} from 'vio';

// extends `Controller` class.
export default class extends Controller {
  // route as a HTTP GET request.
  @get()
  default() {
    // can also be a promise if it's async.
    return {
      title: 'Hello, VIO!',
      content: 'Keep calm and read the doc!',
    };
  }
}

views/default.hbs

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>{{title}}</title>
</head>
<body>
  <h1>{{title}}</h1>
  <p>{{content}}</p>
</body>
</html>

Now compile files in src into bld and run node bld/server.js to start the server.

Please checkout demos for more usage.

Dynamic Loading

The previous version of VIO is used internally in the passed half a year, having handled more than 100 million page views (though it does not mean you can use this version in production). And the biggest issue this version of VIO wants to take out is slow restarting of node process when something changes. It's not a big deal if the code base is small, but when things grow, it would drive people crazy.

Comparing to other hot module replacement implementation (usually by intercepting require mechanism), VIO take things a little bit further. As routes are file path based (which means no manually mapping needed), VIO guess the possible paths based on requesting url and then load the route file on demand. And of course creating, moving, deleting route files would work without restarting node.

Route Matching

The route path is a combination of route file path (relative path to routesRoot) and route path (implied by route method name using hyphenate).

The last default of route file path or route method name, as well as the last part in file path if it's the same as the containing folder name, will be ignored. For example:

Route handler default defined in desktop/default.js file will be matched with route path /desktop instead of /desktop/default or /desktop/default/default.

And if you specified default subsite as desktop, it will match both / and /desktop.

View Matching

Taking a better editor navigation experience and file structure into consideration, view matching accepts more patterns. For example, route path /hello/world would accept view file (take .hbs here) at these paths:

/hello/world.hbs
/hello/world/default.hbs
/hello/world/default/default.hbs
/hello/world/world.hbs
/hello/world/default/world.hbs

Production Mode

Unlike development mode with dynamic loading, production mode loads all routes when process starts and will not care about file changes.

To enable production mode for testing purpose, set environment variable NODE_ENV to "production".

License

MIT License.

Usage no npm install needed!