{"id":31177869,"url":"https://github.com/maxcharm093/falcon-boilerplate","last_synced_at":"2026-04-12T13:35:37.337Z","repository":{"id":311504250,"uuid":"1043843635","full_name":"maxcharm093/falcon-boilerplate","owner":"maxcharm093","description":"Node.js backend boilerplate with express.js socket.io and mysql/postgresql(prisma).","archived":false,"fork":false,"pushed_at":"2025-08-24T18:26:32.000Z","size":93,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-25T00:16:05.852Z","etag":null,"topics":["docker","docker-networking","error-middleware","expressjs","file-upload","mysql","mysql-database","mysql-server","postgresql","prisma","socket-io"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxcharm093.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-08-24T18:26:29.000Z","updated_at":"2025-08-24T18:53:37.000Z","dependencies_parsed_at":"2025-08-25T00:33:23.012Z","dependency_job_id":null,"html_url":"https://github.com/maxcharm093/falcon-boilerplate","commit_stats":null,"previous_names":["maxcharm093/falcon-boilerplate"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/maxcharm093/falcon-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxcharm093%2Ffalcon-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxcharm093%2Ffalcon-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxcharm093%2Ffalcon-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxcharm093%2Ffalcon-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxcharm093","download_url":"https://codeload.github.com/maxcharm093/falcon-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxcharm093%2Ffalcon-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275952448,"owners_count":25558705,"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","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["docker","docker-networking","error-middleware","expressjs","file-upload","mysql","mysql-database","mysql-server","postgresql","prisma","socket-io"],"created_at":"2025-09-19T14:31:25.317Z","updated_at":"2025-09-19T14:32:19.061Z","avatar_url":"https://github.com/maxcharm093.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Falcon Boilerplate\n\u003cimg src=\"https://i.ibb.co/sWqXfkz/Screenshot-from-2024-04-29-15-08-28.png\" align=\"left\" width=\"30%\" style=\"margin-right: 10px\"/\u003e\nFalcon Boilerplate is a service-based Node.js backend boilerplate that will help you kickstart and manage your projects more efficiently. This REST API server boilerplate is built upon a powerful stack of technologies, including Express.js, Socket.io, and MYSQL, to provide a comprehensive solution for web service development and database management. You can work faster like a falcon by using this template.\n\u003cbr clear=\"left\"/\u003e\n\u003cbr clear=\"left\"/\u003e\n\n- [Getting Started](#getting-started)\n  - [Folder Renaming](#folder-renaming)\n  - [Configuration](#configuration)\n  - | With docker    | Without docker   |\n    | :---: | :---: |\n    | [Docker](#docker)   | [Install Dependencies](#install-dependencies)   |\n    || [Database Setup](#database-setup)   |\n    || [Start the Server](#start-the-server)   |\n\n\n- [Creating Services](#creating-services)\n  - [Create the service root file](#create-the-service-root-file)\n  - [Generate service and entity with vs code snippets](#generate-service-and-entity-with-vs-code-snippets)\n  - [Create the api routes and register socket listeners in the service root file](#create-the-api-routes-and-register-socket-listeners-in-the-service-root-file)\n  - [Create entity functions](#create-entity-functions)\n  - [Inject the service in the app](#inject-the-service-in-the-app)\n\n- [Handling Api Error](#handling-api-error)\n- [Serving Client](#serving-client)\n\n\n## Getting Started\n\nFollow these steps to get started with Falcon Boilerplate:\n\n\n1. \u003ca id=\"folder-renaming\"\u003e**Folder Renaming:**\u003c/a\u003e \u003cbr\u003e Start by renaming the `demo_ssl` folder to `ssl` and `demo_settings` to `settings`.\n\n1. \u003ca id=\"configuration\"\u003e**Configuration:**\u003c/a\u003e \u003cbr\u003e Configure your application settings in the `settings/dev.js` file for development and `settings/prod.js` for production. You will get the settings inside every request and socket events. The settings used will be determined by the NODE_ENV variable inside the index.js file at the root.\n\n1. \u003ca id=\"install-dependencies\"\u003e**Install Dependencies**\u003c/a\u003e \u003cbr\u003e Run the following command to install project dependencies:\n\n    ```bash\n    npm install\n    # or\n    yarn install\n    ```\n\n1. \u003ca id=\"database-setup\"\u003e**Database Setup**\u003c/a\u003e \u003cbr\u003e For database you can isntall mysql in your system and place necessary information at settings/dev.js and settings/prod.js.\n\n1. \u003ca id=\"start-the-server\"\u003e**Start the Server**\u003c/a\u003e \u003cbr\u003e Start the server using nodemon to enable hot-reloading during development:\n\n    ```bash\n    yarn dev\n    ```\n\n## Creating Services\nFollow these steps to create a new service:\n\n1. \u003ca id=\"create-the-service-root-file\"\u003e**Create the service root file**\u003c/a\u003e \u003cbr\u003e Start by organizing your services within the `services` directory. Each service should have its own dedicated folder and a corresponding file for the service entry points also a single or multiple entity file for building the core logic.\u003cbr\u003e\nExample:\n    ```plaintext\n    - services\n      | - user\n        | - user.js\n        | - user.entity.js\n    ```\n\n1. \u003ca id=\"generate-service-and-entity-with-vs-code-snippets\"\u003e**Generate service and entity with vs code snippets**\u003c/a\u003e \u003cbr\u003e If you are using vs code. Then there is two vs code snippets to generate the service and entity code with basic crud operation. If you follow this step then you don't need to follow step number 3 and 4.\n    | Trigger | Content                      |\n    | ------: | ---------------------------- |\n    |   `service` | `service code with basic crud api routes and socket function.` |\n    |   `entity` | `entity for the basic crud apies.`  |\n\n\n1. \u003ca id=\"create-the-api-routes-and-register-socket-listeners-in-the-service-root-file\"\u003e**Create the api routes and register socket listeners in the service root file**\u003c/a\u003e \u003cbr\u003e\nService Root File (e.g., user.js):\n    ```javascript\n    const { create, handleClickButton } = require('./user.entity');\n\n    /**\n     * INSTRUCTIONS:\n     * 1. Call API and socket handler functions from entity file (e.g., user.entity.js).\n     */\n\n    /**\n     * Define API routes for user management.\n     */\n    function userApi() {\n\n      /**\n       * POST /user\n       * @description This route is used to create a user.\n       * @response {Object} 201 - The new user.\n       * @body {Object} - The data to create a user.\n      */\n      this.router.post('/user', create(this));\n    }\n\n    /**\n     * Register event handlers for user-related events.\n     */\n    function userSocket() {\n          this.socket.on('clickedButton', handleClickButton(this));\n    }\n\n    module.exports = { userApi, userSocket };\n    ```\n\n1. \u003ca id=\"create-entity-functions\"\u003e**Create entity functions**\u003c/a\u003e \u003cbr\u003e\nEntity File (e.g., user.entity.js):\n    ```javascript\n    const TABLE_NAME = 'user';\n\n    module.exports.create = ({ db }) =\u003e async (req, res, next) =\u003e {\n        try {\n            const { role } = req.params;\n            let { first_name, last_name, phone, email, password } = req.body;\n            password = await bcrypt.hash(password, 8);\n            await db.execute(`CALL register(?, ?, ?, ?, ?, ?)`, [first_name, last_name, phone, email, password, role]);\n            res.status(201).send({ message: 'User registration successful' });\n          } catch (e) { next(e) }\n    };\n\n    module.exports.handleClickButton = async ({ db }) =\u003e {\n      // Implement the functionality you need.\n    }\n    ```\n    `Note: In this boilerplate, all functions are connected to the Falcon class. This gives you access to various features, like I have accessed the db above. It also allows you to easily add new tools and functionalities to the Falcon class and access them globally.`\n\n## Inject the service in the app\nLastly For making the service available for your clients you have to inject that in the app.\u003cbr\u003e\nFollow these steps:\n\n1. **Inject api service**: \u003cbr\u003e\n    ```diff\n    const { errorMiddleware } = require(\"./middlewares\");\n    +const { userApi } = require(\"./user/user\");\n\n    function apiServices() {\n    + userApi.call(this);\n      this.router.use(errorMiddleware(this))\n    };\n    ```\n\n2. **Inject socket service**: \u003cbr\u003e\n    ```diff\n    const { errorMiddleware } = require(\"./middlewares\");\n    +const { userApi, userSocket } = require(\"./user/user\");\n\n    function apiServices() {\n      userApi.call(this);\n      this.router.use(errorMiddleware(this))\n    };\n\n    function socketServices() {\n    +  userSocket.call(this);\n    };\n    ```\n    As simple as that. Your services are good to go now.\n\n## Handling Api Error\nIn the entity, if you invoke the `next` function of express with an `Error` instance as its first parameter, the `errorMiddleware` function will be triggered. The error will be permanently logged in the `data/server_error/{year}/{month}/{day}.log` file, and the client will receive a 500 response with a reference id. If reference id is not found in the response, it means the middleware failed to save the error. The error log can be found in the console.\n```javascript\nmodule.exports.create = ({ db }) =\u003e async (req, res, next) =\u003e {\n  try {\n    const user = await db.create({ table: TABLE_NAME, payload: { data: req.body } });\n    return res.status(201).send(user);\n  } catch (e) { next(e) }\n};\n```\n\n## Serving client\nYou can place your client code inside the `client` folder. The Falcon boilerplate will search for the `index.html` file to serve the client.\n\n## Docker\n\n```bash\n# Creating bridge type network (if not already exists)\n# The database and the api will be in this network.\ndocker network create -d bridge falcon\n```\n\nTwo Docker Compose files are provided:\n\n- `compose_dev.yml`: For development mode.\n- `compose.yml`: For production mode.\n\n```bash\n# Running in Development Mode\ndocker compose -f compose_dev.yml up --watch\n\n# Rebuilding API Image (if needed)\ndocker compose -f compose_dev.yml up --build --watch\n```\n\n```bash\n# Running in Production Mode\ndocker compose up -d\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxcharm093%2Ffalcon-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxcharm093%2Ffalcon-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxcharm093%2Ffalcon-boilerplate/lists"}