Getting Started

Overview

This tutorial will show how to set up a basic backendjs server that displays "Hello World!" in your browser.

Installing backendjs

Create a new directory myproject, and from there run:

cd myproject
npm install vseryakov/backendjs --save

this will install the latest version of backendjs as a dependency in your package.json.

Creating a Web Server

A very basic backendjs Web server looks like the following:

const { app, api } = require('backendjs');
app.start({ api: 1 });
console.log('Server running on http://%s:%s', api.bind, api.port);

First, you require backendjs. Then you start the server with default settings and log that it's running, the api property tells to start Express web server, i.e. the api mode. There are more server modes available.

Run node and then paste the three lines above into it.

Now visit http://localhost:8000 in your browser, you'll see the text 'Hello, World!'.

This is default empty index.html bundled with the server.

Creating a module

Now let's create a simple module that will increase a counter every time you refresh the page and persist it in the Sqlite database.

Save the lines below as index.js

const { app, api, db } = require('backendjs');

const mod = {
    name: "counter",

    tables: {
        counter: {
            id: { type: "int", primary: 1 },
            value: { type: "counter" },
            mtime: { type: "now" },
        }
    },

    configureWeb(options, callback)
    {
        api.app.get("/counter", this.getCounter);

        callback();
    },

    getCounter(req, res)
    {
        db.incr("counter", { id: 1, value: 1 }, { returning: "*", first: 1 }, (err, row) => {
            api.sendJSON(req, err, row);
        });
    }

}
app.addModule(mod);

app.start({ api: 1 });
console.log('Server running on http://%s:%s', api.bind, api.port);

Then save the following lines as bkjs.conf

api-acl-add-public=^/counter
db-sqlite-pool=counter
db-pool=sqlite

Now run the command

node index.js -db-create-tables

Go to http://localhost:8000/counter in your browser, you'll see the current counter value, refresh it and see the counter value incrementing with mtime timestamp in milliseconds.

Explanation about this example:

• the counter module is just an object with a name, here we created it inside the same index.js but modules usually placed in its own separate files
• the tables object describes SQL table "counter" with 3 columns
• the configureWeb method is called by the server on start, this method is reserved for adding your Express routes, it is called only in the "api" mode where api.app is the Express application.
• we just created a single GET route /counter using Express middleware syntax, inside we directly increment the counter in the record with id=1, it is created automatically on first call
• then return the whole record back as JSON, it is ok to do it for such a silly example.
• the bkjs.conf file is created for convenience, we could pass all params via the command-line
• the config defines Sqlite database pool with file named "counter" and adds our /counter endpoint to the public access list, by default all endpoints require some kind of access permissions
• and lastly we pass -db-create-tables to the node to initialize the database, this is usually need only once or every time the schema changes, so next time it is fine to just run the demo as node index.js

This example is in the repository at starter.

Next steps

backendjs has many, many other capabilities like module:api, module:db, module:jobs, module:cache, module:queue, module:aws.

Please explore the documentation and examples at examples.