@russo-programmisto/manifest NPM

At a Glance

Manifest is a framework that takes control over Node.js app using a single configuration file. Manifest includes Express framework and Handlebars server-side rendering under the hood.

How to Get Started

Type in Terminal:

npm install --save @russo-programmisto/manifest express hbs express-hbs
npm install --save-dev @types/express @types/hbs

or, if you prefer yarn over npm, type:

yarn add @russo-programmisto/manifest express hbs express-hbs
yarn add @types/express @types/hbs --dev

Requirements

Usage

Launching App

The simplest way to start Express server:

import * as mfst from "@russo-programmisto/manifest";

mfst.App.create().start();

Open localhost:3000 in your browser. You will see a message saying Built with Manifest framework.

That's all! The server is launched 🚀

By the way, you can access Express instance directly by calling

app.expressInstance

Quite simple, right? 😉

Server Configuration

Now let's learn how to configure our server:

import * as mfst from "@russo-programmisto/manifest";

let app = mfst.App.create({
    server: {
        port: 3000,          // Use any port, usually it's 3000
        secure: false       // HTTP or HTTPS
    },
    api: {
        routes: [
            {
                url: `/`,
                methods: {
                    get: {
                        text: `<h1>This page is under construction</h1>`,
                    }
                }
            },
            {
                url: "/users",
                    methods: {
                        get: {
                            json: {
                                count: 200,
                                users: [
                                    {
                                        id: 1,
                                        first_name: "John",
                                        last_name: "Appleseed"
                                    },
                                    // etc...
                                ]
                            }
                        },
                        post: {
                            handler: (req, res) => {
                                const { first_name, last_name } = req.body;
                                
                                if (first_name && last_name) {
                                    // Create user in database...
                                    return {
                                        json: {
                                            id: 123,
                                            first_name,
                                            last_name
                                        },
                                        status: 200
                                    };
                                } else {
                                    return {
                                        json: {
                                            message: "Please make sure that you send first_name and last_name parameters."
                                        },
                                        status: 400
                                    };
                                }
                            }
                        }
                    }
                },
            {
                url: `*`,
                methods: {
                    get: {
                        text: `<h1>Page not found</h1>`,
                        status: 404,
                        timeout: 2000
                    }
                }
            }
        ],
    }
});

app.start();

In the above example you can see a very simple configuration that is enough to launch a primitive server which will be able to respond to HTTP requests.

Manifest Sections

`server.port`

Port number that server will be listen to.

`server.secure`

If true, HTTPS will be used under the hood. Otherwise, we'll use unsecure HTTP.

`server.corsBlocked`

If true, CORS will be enabled for all endpoints.

`api.requestHandlers`

Array of functions. Each function has request parameter and handles request before it's processed by Manifest framework. You can use handlers for any purpose. For example, sending request information to the console output:

requestHandlers: [
    (request) => {
        console.log(`Request to ${request.url}`);
    }
]

`api.routes`

Array of objects. Each object represents a different route. Example:

{
    routes: [
        {
            url: "/",
            methods: {
                get: {
                    text: "Hello!"
                },
                post: {
                    text: "Post response."
                },
                put: {
                    text: "Put response."
                },
                delete: {
                    text: "Delete response."
                }
            }
        }
    ]
}

The methods object can include any of these HTTP methods:

get
post
put
delete

Each HTTP method describes the response to client's request. Manifest supports 5 types of response:

Text (returns simple text)
JSON (returns JSON object or array)
Page (returns page and data for server-side rendering)
Redirect (sends command for redirection to another URL)
Custom (arrow function that is implemented by developer and returns text or JSON or page response)
Custom asynchronous (arrow function that is implemented by developer and returns text or JSON or page response by using callback)

Example of text response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    text: "<h1>John Green</h1>"
                }
            }
        }
    ]
}

JSON response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    json: {
                        first_name: "John",
                        last_name: "Green"
                    }
                }
            }
        }
    ]
}

Page response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    path: `${__dirname}/views/profile.hbs`,
                    data: {
                        // Optional data that will be used by Handlebars engine.
                        firstName: "John",
                        lastName: "Green"
                    }
                }
            }
        }
    ]
}

Redirect response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    redirectTo: "/not_found"
                }
            }
        }
    ]
}

Custom response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    handler: (request, response) => {
                        let firstName = "John";
                        let lastName = "Green";

                        // We have to return text or JSON or page response here.
                        return {
                            json: {
                                first_name: firstName,
                                last_name: lastName
                            }
                        };
                    }
                }
            }
        }
    ]
}

Custom asynchronous response:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    asyncHandler: (request, response, callback) => {
                        let firstName = "John";
                        let lastName = "Green";
                        
                        // Return response using callback.
                        callback({
                            json: {
                                first_name: firstName,
                                last_name: lastName
                            }
                        });
                    }
                }
            }
        }
    ]
}

Also, most of response types support optional parameters:

status: HTTP status, by default 200
delay: The duration in milliseconds of delay before returning response.

Example of using custom HTTP status:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    text: "<h1>Not found</h1>",
                    status: 404
                }
            }
        }
    ]
}

Sometimes you might want to simulate slow server. Use delay for this purpose:

{
    routes: [
        {
            url: `/profile`,
            methods: {
                get: {
                    json: {
                        first_name: "John",
                        last_name: "Green"
                    },
                    delay: 4000
                }
            }
        }
    ]
}