{"id":14970059,"url":"https://github.com/neobeach/core","last_synced_at":"2025-10-26T11:31:20.272Z","repository":{"id":37403928,"uuid":"474071696","full_name":"neobeach/core","owner":"neobeach","description":"Base web framework based on the popular ExpressJS package","archived":false,"fork":false,"pushed_at":"2024-12-11T20:05:25.000Z","size":587,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-31T18:56:45.706Z","etag":null,"topics":["backend-service","express","expressjs","framework","service"],"latest_commit_sha":null,"homepage":"https://neobeach.dev/core/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neobeach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-25T15:48:52.000Z","updated_at":"2024-12-11T20:05:25.000Z","dependencies_parsed_at":"2024-09-27T12:41:42.575Z","dependency_job_id":"658d0f7d-a389-42ee-9352-96b2884df9c7","html_url":"https://github.com/neobeach/core","commit_stats":{"total_commits":43,"total_committers":2,"mean_commits":21.5,"dds":0.09302325581395354,"last_synced_commit":"957f9a8ad8c7fbb4905c86563eecaedd8ae9758d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neobeach%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neobeach%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neobeach%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neobeach%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neobeach","download_url":"https://codeload.github.com/neobeach/core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238319450,"owners_count":19452339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend-service","express","expressjs","framework","service"],"created_at":"2024-09-24T13:42:58.092Z","updated_at":"2025-10-26T11:31:19.869Z","avatar_url":"https://github.com/neobeach.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# neobeach/core\n\nBase web framework based on the popular ExpressJS package\n\n## Why?\nThe neobeach/core package aims to provide a base webserver application structure based on the popular Express.JS package.\nThe Core also provides some ready to go implementations for implementing useful and ready-to-go middlewares and frameworks.\nWe also implement a basic MVC structure that only consists of the Routers and Controllers, after that you are free to either continue your business logic in the Controller or for example go into Services, Repositories, Models or Utils.\n\nThe Core is completely modular, this means that we only install the dependencies we really need. As soon as you implement a feature that requires another dependency we just simply ask you to install that within your project.\nThis keeps the amount of dependencies to a minimum, and the overall package size small. Making it perfect for container architecture\n\n## Project Structure\nHere you will find an example application folder structure, this also explains which files are required:\n```text\nexample/                 \u003c-- Project Root\n  config/                \u003c-- Application config (Required)\n    config.json          \u003c-- Environment specific config, normally not stored within GIT (Required)\n    default.json         \u003c-- Application specific config, normally stored in GIT (Required)\n  controllers/           \u003c-- Contains all application Controllers (Optional, Technically you can store them everywhere but we do recommend creating a folder for it)\n    api/                 \u003c-- Contains all Api controllers (Optional)\n      IndexController.js \u003c-- Contains all Index/Home handlers for the Api controller (Optional)\n    web/                 \u003c-- Contains all Web controllers (Optional)\n      IndexController.js \u003c-- Contains all Index/Home handlers for the Web controller (Optional)\n  middlewares/           \u003c-- Contains all application Middlewares  (Optional, Technically you can store them everywhere but we do recommend creating a folder for it)\n    RequestLogger.js     \u003c-- This file exports a simple Express middleware (Optional)\n  models/                \u003c-- Contains all application Sequelize ORM Models (Optional)\n    User.js              \u003c-- Contains the User model for the Sequelize ORM (Example)\n  routers/               \u003c-- Contains all application Routers (Optional, Technically you can store them everywhere but we do recommend creating a folder for it)\n    Api.js               \u003c-- Contains all Api routes and references Controllers to handle a specific sub-path (Optional)\n    Web.js               \u003c-- Contains all Web routes and references Controllers to handle a specific sub-path (Optional)\n  package.json           \u003c-- Contains all your project dependency information (Required)\n  server.js              \u003c-- Main entry file for the application, this initializes the Core and binds for example additional Routers or middlewares (Required)\n```\n\n## Versions\nThe current version of the Core is build/tested on the following dependency versions:\n```text\nnode: \"18.13.0\"\nnpm: \"8.5.0\"\n\n@remix-run/express: \"1.3.4\"\ncompression: \"1.7.4\"\ncookie-parser: \"1.4.6\"\ncors: \"2.8.5\"\ndeepmerge: \"4.2.2\"\nejs: \"3.1.8\"\nexpress: \"4.18.2\"\nhelmet: \"6.0.1\"\njs-logger: \"1.6.1\"\nmulter: \"1.4.5-lts.1\"\nnode-fetch: \"2.6.8\"\nsequelize: \"6.28.0\"\nsqlite3: \"5.1.4\"\n```\n\n## Config\nSome default application config is already for you defined and can be overridden in your `config/default.json` or `config/config.json`:\n\n```javascript\nconst dev = process.env.NODE_ENV !== 'production';\n\nconst baseConfig = {\n    application: {\n        env: dev,\n        host: '0.0.0.0',\n        port: 3000,\n        node: 18\n    },\n    logger: {\n        level: 'DEBUG'\n    },\n    database: {\n        dialect: 'sqlite'\n    }\n};\n```\n\n### Usage\nBelow you will find an example on how to access config elements:\n```javascript\nconst {Config} = require('@neobeach/core');\n\nconsole.log('config', config);\nconsole.log('config.application.host', config.application.host);\n```\n\n### Config Order\nThere are multiple config files available for you to use. These are merged in the following order and have a particular role:\n\n```text\nConfig.js    \u003c-- Base config provided by the Core.\ndefault.json \u003c-- Lives inside a project and is checked into GIT. This config is therefore available on all environments.\nconfig.json  \u003c-- Lives inside a project and is not checked into GIT. The config is therefore environment specific.\n```\n\n### Config Location\nThe Core will by default expect a `config` directory from the point where you initialize the application.\nYour project layout would then be:\n```text\nexample/                 \u003c-- Project Root\n  config/                \u003c-- Application config (Required)\n    config.json          \u003c-- Environment specific config, normally not stored within GIT (Required)\n    default.json         \u003c-- Application specific config, normally stored in GIT (Required)\n  package.json           \u003c-- Contains all your project dependency information (Required)\n  server.js              \u003c-- Main entry file for the application, this initializes the Core and binds for example additional Routers or middlewares (Required)\n```\n\nIn this case your entry point would be the server.js file\n\nHowever, it may be required to change this. Let's pretend the app is one folder deeper then the entry file.\nYour project layout would then be:\n```text\nexample/                 \u003c-- Project Root\n  app/                   \u003c-- App Root\n    config/              \u003c-- Application config (Required)\n      config.json        \u003c-- Environment specific config, normally not stored within GIT (Required)\n      default.json       \u003c-- Application specific config, normally stored in GIT (Required)\n  package.json           \u003c-- Contains all your project dependency information (Required)\n  server.js              \u003c-- Main entry file for the application, this initializes the Core and binds for example additional Routers or middlewares (Required)\n```\n\nIn this case your entry point would be the server.js file, but the config folder is inside the `app/config folder`\n\nTo ensure the application knows about this we can override an environment variable like this:\n```text\nCONFIG_DIR=/app/config/\n```\n\n## Logging\nThe Core logger can be imported at any moment. This can be used to output logs to the console.\nThe following functions will be available to log to the console accordingly to the log level that can be set inside the config:\n\n```javascript\nconst {Logger} = require('@neobeach/core');\n\nLogger.trace('This is a message'); // Outputs a log within the trace, debug, info, warn and error log-level with stacktrace\nLogger.debug('This is a message'); // Outputs a log within the debug, info, warn and error log-levels\nLogger.info('This is a message');  // Outputs a log within the info, warn and error log-levels\nLogger.warn('This is a message');  // Outputs a log within the warn and error log-levels\nLogger.error('This is a message'); // Outputs a log within the error log-level\n```\n\n### Log Level\nThe application default log level is `TRACE`, valid options are: `TRACE`, `DEBUG`, `INFO`, `WARN` and `ERROR`.\nYou can change the log level by updating the application config:\n```json\n{\n  \"logger\": {\n    \"level\": \"TRACE\"\n  }\n}\n```\n\n## Database\nThe Core implements Sequelize as it's ORM for connecting to many SQL services.\nHere is a small list of all supported database engines:\n\n```text\nmysql\npostgres\nsqlite\nmariadb\nmssql\ndb2\nsnowflake\noracle\n```\n\nBy default, we utilize sqlite and the packages for that engine are installed by default.\nTo switch engines and supply more configuration options to Sequelize, use the `database` object inside your `default.json` or `config.json`.\n\n\u003e Sequelize configuration options can be found here: https://sequelize.org/api/v6/class/src/sequelize.js~sequelize#instance-constructor-constructor\n\n\u003e Make sure when switching database engines you install the appropriate packages needed by Sequelize: https://sequelize.org/docs/v6/getting-started/#installing\n\n### Usage\nBelow is some example code on how to initialize the database connection.\nAfter that we do a simple `COUNT` query on an example model (also provided in the example below).\n\n#### server.js\n```javascript\n/**\n * Import vendor modules\n */\nconst {Runtime, db} = require('@neobeach/core');\n\n/**\n * Import own modules\n */\nconst User = require('./models/User');\n\n/**\n * Create a runtime/sandbox to start the server in\n */\nRuntime(async () =\u003e {\n    await db.init([User]);\n    const userCount = await db.models.User.count();\n\n    console.log('userCount', userCount);\n});\n```\n\n#### User.js\n```javascript\n/**\n * Import vendor modules\n */\nconst {DataTypes} = require('sequelize');\n\n/**\n * Define the User model\n *\n * @param db\n */\nmodule.exports = (db) =\u003e {\n    db.define('User', {\n        uuid: {\n            type: DataTypes.UUID,\n            defaultValue: DataTypes.UUIDV4,\n            primaryKey: true,\n            unique: true\n        },\n        email: {\n            type: DataTypes.STRING,\n            validate: {\n                isEmail: true,\n                notEmpty: true\n            }\n        },\n        firstName: {\n            type: DataTypes.STRING,\n            validate: {\n                notEmpty: true\n            }\n        },\n        lastName: {\n            type: DataTypes.STRING,\n            validate: {\n                notEmpty: true\n            }\n        },\n        fullName: {\n            type: DataTypes.VIRTUAL,\n            get() {\n                return `${this.firstName} ${this.lastName}`;\n            },\n            set() {\n                throw new Error('Do not try to set the `fullName` value!');\n            }\n        }\n    }, {\n        tableName: 'users'\n    });\n};\n```\n\n\u003e More documentation on writing Sequelize models can be found here: https://sequelize.org/docs/v6/core-concepts/model-basics/\n\n## Middlewares and Functions\nBelow is an overview of all main Server/Core functions:\n```javascript\nserver.loadMiddlewares(middlewares);    // Load global middlewares into the Express app\nserver.loadRouters(routers);            // Load routers into the Express app\nserver.loadStatic(directory, prefix);   // Serves a static directory from the Express app\n\nserver.setParameter(name, value);       // Sets an Express app parameter\nserver.setEJSViewEngine(views);         // Sets the Express render engine to EJS\n\nserver.includeDefaultBodyParsers();     // Includes/loads default express body parsers (json, text, urlencoded and multer) with recommended config into the Express app\nserver.includeDefaultSecurityHeaders(); // Includes/loads default security headers with recommended config into the Express app\nserver.includeDefaultCorsHeaders();     // Includes/loads default CORS headers with recommended config into the Express app\nserver.includeDefaultCompression();     // Includes/loads default compression (deflate, gzip) with recommended config into the Express app\nserver.includeDefaultCookieParser();    // Includes/loads cookie parser with recommended config into the Express app\n\nserver.loadRemixFramework(serverBuild); // Attach a Remix Framework build to our Express server\n\nserver.run();                           // Starts the Express server\n```\n\n## Healthcheck\nOn creation of a new Server, every express instance will contain a simple healthcheck.\nThis healthcheck can be accessed via the `/_health` url, and reports back some basic application information.\nAn example of the response can be found here:\n\n```json\n{\n  \"status\": \"UP\",\n  \"host\": \"gHAUVLQsWff7BkRR\",\n  \"core\": \"1.0.0\",\n  \"load\": {\n    \"user\": 240214,\n    \"system\": 60369\n  },\n  \"mem\": {\n    \"rss\": 45084672,\n    \"heapTotal\": 19812352,\n    \"heapUsed\": 10697488,\n    \"external\": 2473177,\n    \"arrayBuffers\": 85876\n  },\n  \"uptime\": 1.839386098\n}\n```\n\n\u003e To ensure a fast response time, the healthcheck is initialized before any other middleware. This also keeps the logs free from clutter.\n\n## Upgrade Check\nThe Core checks on every start of the server if an update is available on NPM.\nIf an update is available you will encounter the following message:\n\n```text\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Warning !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n You are running an outdated version of the @neobeach/core package, Please update soon !\n\n Installed version: x.y.z\n Available version: x.y.z\n!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Warning !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!\n```\n\nYou can skip this check by specifying the following environment variable:\n```text\nSKIP_UPGRADE_CHECK=true\n```\n\n## Example App\n### server.js\nBelow you will find an example server.js:\n```javascript\n/**\n * Import modules\n */\nconst {Runtime, Server} = require('@neobeach/core');\nconst Api = require('./Api');\n\n/**\n * Setup a new Express server\n */\nconst server = new Server();\n\n/**\n * Define global middlewares\n */\nconst globalMiddleware = [\n    (req, res, next) =\u003e {\n        // Execute custom code here\n        next();\n    }\n];\n\n/**\n * Define custom routers\n */\nconst routers = [\n    Api\n];\n\n/**\n * Create a runtime/sandbox to start the server in\n */\nRuntime(() =\u003e {\n    server.includeDefaultBodyParsers();\n    server.loadMiddlewares(globalMiddleware);\n    server.loadRouters(routers);\n    server.run();\n});\n```\n\n### Api.js\nBelow you will find an example Api.js:\n```javascript\n/**\n * Import modules\n */\nconst {Router} = require('@neobeach/core');\nconst IndexController = require('./IndexController');\n\n/**\n * Initialize new Router\n */\nconst router = new Router('Api');\n\n/**\n * Add routes to router\n */\nrouter.add('/api', IndexController);\n\n/**\n * Exports the Api router\n */\nmodule.exports = router;\n```\n\n### IndexController.js\nBelow you will find an example IndexController.js:\n```javascript\n/**\n * Import modules\n */\nconst {Controller} = require('@neobeach/core');\n\n/**\n * Initialize new Controller\n */\nconst controller = new Controller('IndexController');\n\n/**\n * Add routes to controller\n */\ncontroller.get('/', [], (req, res) =\u003e {\n    res.json(1000, {\n        hello: 'world!'\n    });\n});\n\n/**\n * Exports the IndexController\n */\nmodule.exports = controller;\n```\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneobeach%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneobeach%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneobeach%2Fcore/lists"}