0.1.11 • Public • Published

    Minoss - Mini Node Script Server

    GitHub version NPM version Dependency version

    This is a small yet powerful server based on node.js and express. It's designed to simple create and serve usable APIs for automatising things, like with the Raspberry Pi or whenever it's needed to easily execute scripts. Minoss is very easy to extend for your needs.

    Build in it has a automatically file loading, handling abstractions and configurations on many levels. Just place the files on the right place and the Server will handle anything else.

    Table of Contents


    Minoss can easily be installed with npm.

    $ npm install minoss

    If installed this way, it's only needed to require minoss in the starting script file. Like in an own server.js file:


    Installation in own Folder

    Another way is, inside a folder where wanted to install Minoss, just to download the project files. It's possible to download the zip archive from GitHub or use git to download the latest files. With this way the core files of Minoss are stored inside the root folder.

    $ git clone https://github.com/dkern/minoss.git .

    Install Modules

    If you want to use other public modules, the easiest way to install them is to use npm. For example:

    $ npm install minoss-example


    Minoss itself only has a very small configuration. You will find anything with a description inside the config/server.js file. Change the options as you like.

    name default description
    debug false enable debug mode to have a verbose console output
    port 8080 port number to listen on after start
    xmlRootTag root name of the xml root tag

    Custom Routes

    The routes.js configuration allows you to add own routes to the server. Because Minoss is based on express you can use it's full routing functions.

    module.exports = app => {
        app.get('/example', (req, res) => {
            res.send("example response");

    Start Minoss

    The server can be started one time by using npm start or manually by node server.js inside the directory where you installed it.

    $ node server.js

    After start a message should notice about where the server is listening by now.

    Minoss now listening on http://localhost:8080 ...

    Let Minoss run forever

    You may want to let the server running forever and automatically start it after reboot or crash. Therefore you could use pm2, a process manager for node.js.

    If you didn't use pm2 already, you can install it globally.

    $ npm install -g pm2

    Once installed you can add Minoss execution to the handling of pm2:

    $ pm2 startup
    $ pm2 start server.js --name minoss
    $ pm2 save

    And that's it, your server will now run automatically on every boot, pm2 will even restart Minoss when it crashes. If you want to stop it with pm2 stop minoss.

    Call a Module-Script

    You call and execute a script always by module and script name. Minoss will do anything else for you.


    Output Formats

    Minoss supports three different output types by default: json, xml and plain text, while json is the default. You can switch between them every time. Just put the wanted output format before the module and script name, or append it as get parameter.


    Possible calls:


    Will output something like:

      "success": true


    Possible calls:


    Will output something like:

    <?xml version='1.0'?>


    Possible calls:


    The text output format will return 1 on success and 0 on failure. If an error message is available it will be return just the message itself. So in short, everything not 1 is an error.

    Available Modules

    There are currently only a few modules available by myself. Feel free to create own Modules on your own or spread some new ones with other.

    Create an own Module

    Creating a module is just creating a new folder in the Minoss root directory. The name of the directory is the name of the module. Inside this directory all executable scripts takes place. The name of the Files are also the name of the script.

    For example, when creating a folder and file named example/test.js, the module is named example and the dcript is named test. So the URl would be something like http://hostname:8080/example/test.

    More details and a full example can be found inside the minoss-example repository.

    Creating an executable Script for a Module

    A Script must always export a function. This function has four parameters, which will be filled by Minoss on request of this script.

    module.exports = (config, params, respond, error) => {
    name type description
    config object contains all configurations for this module
    params object contains all parameters given by request url
    respond function callback function for browser response
    error function callback function for errors

    'config' Parameter

    The config parameter is an object, containing all configuration data from this Module. The properties inside this object are the config file names. If there would be two config Files, named config/foo.js and config/bar.js, the object would be look like this:

    let config = {
        foo: {
            // export of config/foo.js
        bar: {
            // export of config/bar.js

    'params' Parameter

    The params parameter is an object, containing all parameters given by URL on this request. It will at least contain the module, script and output parameters. Assuming a request URL like http://localhost:8080/example/test?mode=get&id=1 the object would be look like this:

    let params = {
        module: 'example',
        script: 'test',
        output: 'json',
        mode: 'get',
        id: 1

    'respond' Parameter

    The respond callback function is used to tell Minoss that your script is finished and for responding additional data. It can handle true and false as parameter, for telling success or fail, or an object with more data. There should be no further output after this has been called.

    respond(true);  // shorthand for: {success: true}
    respond(false); // shorthand for: {success: false}
    respond({success: true, data: 'myData'});

    'error' Parameter

    The error callback is optional and can be used for responding errors. It can be done with the respond callback too, but it is a shorthand for this task and would make your script more readable. The only parameter of this function can be a message as string or an object with additional data. There should be no further output after this has been called.

    error('error message'); // shorthand for: {success: false, error: "error message"}

    Configure a Module

    Many modules would need configuration files. If you install modules with npm you would lost these or have to edit files in the node_modules folder. Each is not quite usable.

    Because of this you can place all your configurations inside the config/ folder of the Minoss root, or in a local module instance. The sever will select these files then instead. The order for overwriting configuration is: node installed module -> local module -> root 'config/' folder

    To overwrite a configuration with a local instance, just create a sub-folder there, with the name of the module you want to override and place the configs there.

      |- hue/              <-- module name
        |- config/
          |- bridges.js    <-- overriding configuration

    Another way, if you don't need a local module, is to place all configurations in the config/ directory of the root folder. Just create a sub-folder with the name of the module you want to override.

      |- config/
        |- hue/            <-- module name
          |- bridges.js    <-- overriding configuration
        | - messages.js
        | - server.js

    Overwrite Module Files

    It is possible to override files of other modules, installed with npm. There is no need to copy the whole module. Just copy the script you want to change inside a local module folder.

      |- config/
      |- node_modules/
        |- minoss-example
          |- example.js      <-- the file you want to override
      |- src/
      |- .jshintrc
      |- gulpfile.js
      |- package.json
      |- README.md
      |- server.js
      |- config/
      |- example/
        |- example.js        <-- place it here to override
      |- node_modules/
        |- minoss-example
          |- example.js
      |- src/
      |- .jshintrc
      |- gulpfile.js
      |- package.json
      |- README.md
      |- server.js

    You only need to change the require entries to the correct files, if used, and you're ready to go. All other scripts will be loaded from node_modules/example/ like before.

    Validate Scripts

    Because you will not see all errors on blind execution of your scripts, there is a build in javascript validation with gulp and jshint. You can execute this validation whenever you like, or let it watch for file changes, with the following commands:

    $ gulp validateAll
    $ gulp validate
    $ gulp watch

    Bugs / Feature request

    Please report bugs and feel free to ask for new features directly on GitHub.


    Minoss is dual-licensed under MIT and GPL-2.0 license.


    You like to support me?
    You appreciate my work?
    You use it in commercial projects?

    Feel free to make a little donation! 😉


    npm i minoss

    DownloadsWeekly Downloads





    (MIT OR GPL-2.0)

    Unpacked Size

    35.3 kB

    Total Files


    Last publish


    • eisbehr