{"id":15295977,"url":"https://github.com/alex-levacher/lumie","last_synced_at":"2025-04-05T10:08:57.741Z","repository":{"id":44896450,"uuid":"53283534","full_name":"Alex-Levacher/Lumie","owner":"Alex-Levacher","description":"✨ An opinionated way to keep your express API organized","archived":false,"fork":false,"pushed_at":"2022-01-20T04:00:08.000Z","size":967,"stargazers_count":280,"open_issues_count":6,"forks_count":19,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-04-14T13:10:20.518Z","etag":null,"topics":["api","architecture","controllers","expressjs","framework","javascript","loader","nodejs"],"latest_commit_sha":null,"homepage":"","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/Alex-Levacher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-07T00:17:29.000Z","updated_at":"2024-03-17T18:32:43.000Z","dependencies_parsed_at":"2022-09-24T22:50:56.347Z","dependency_job_id":null,"html_url":"https://github.com/Alex-Levacher/Lumie","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alex-Levacher%2FLumie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alex-Levacher%2FLumie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alex-Levacher%2FLumie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Alex-Levacher%2FLumie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Alex-Levacher","download_url":"https://codeload.github.com/Alex-Levacher/Lumie/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247318745,"owners_count":20919484,"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":["api","architecture","controllers","expressjs","framework","javascript","loader","nodejs"],"created_at":"2024-09-30T18:08:49.189Z","updated_at":"2025-04-05T10:08:57.720Z","avatar_url":"https://github.com/Alex-Levacher.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/fold_left.svg?style=social)](http://bit.ly/Share-Lumie-twitter)\n\n![Lumie Logo](https://raw.githubusercontent.com/Alex-Levacher/Lumie/master/images/Lumie.png)\n\n## 🤔 DESCRIPTION\n\nLumie is a lightweight module that allows you to set up a scalable controllers architecture for your nodejs project.\n\n✅ Maintainable\u003cbr\u003e\n✅ Scalable\u003cbr\u003e\n✅ Quick setup\u003cbr\u003e\n✅ Easily testable\u003cbr\u003e\n\n## 💾 INSTALLATION\n\n```bash\nnpm install lumie\n```\n\n## 🔩 HOW IT WORKS\n\n**Lumie** goes through the files and folders inside your controllers directory to find what we call \"routing definitions\".\u003cbr\u003e\nEach controllers are defined in files, which export their routing definitions [( example )](https://github.com/Alex-Levacher/Lumie/tree/master/example)\u003cbr\u003e\u003cbr\u003e\nBy default, we use the name of the file that exports the routing definition to name the route\n\n`/` \u003e `controllers` \u003e `cars.js` will create the endpoints `/cars/*`\u003cbr\u003e\n`/` \u003e `controllers` \u003e `admin` \u003e `rules.js` will create the endpoints `/admin/rules/*`\u003cbr\u003e\n`/` \u003e `controllers` \u003e `users` \u003e `users.routing.js` will create the endpoints `/users/*`\n\n## ⚙️ CONFIGURATION\n\n```js\nconst express = require(\"express\");\nconst path = require(\"path\");\nconst lumie = require(\"lumie\");\n\nconst app = express();\n\nlumie.load(app, {\n  preURL: \"api\",\n  verbose: true,\n  ignore: [\"*.spec\", \"*.action\"],\n  controllers_path: path.join(__dirname, \"controllers\")\n});\n\nconst server = app.listen(3000, \"127.0.0.1\", () =\u003e {\n  const { address, port } = server.address();\n  console.log(\"Example app listening at http://%s:%s\", address, port);\n});\n```\n\n### Options\n\n| Name                 | type       | default value                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |\n| -------------------- | ---------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **verbose**          | `boolean`  | `false`                               | Will print or not the routes name in the console                                                                                                                                                                                                                                                                                                                                                                                                                                                 |\n| **preURL**           | `string`   | `/`                                | Prefix your route URLs                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |\n| **ignore**           | `string[]` | `null`                                | Lumie will not try to find a routing definition in those files.                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| **controllers_path** | `string`   | none, this option is required | The path of your controllers folder.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |\n| **routing_files**    | `string`   | `*.routing`                           | How you want to name routing files.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |\n| **permissions**      | `function` | `null`                                | A function that takes in parameter a **level access** and returns an [**express middleware**](https://expressjs.com/en/guide/using-middleware.html). This is useful if you want to restrict access for some URLs. With this option enabled, you will be able to set in each route configuration an option level that will be passed to your permission function [( example )](https://github.com/Alex-Levacher/Lumie/blob/master/example/permissions.js) |\n\n## 🌲FILE STRUCTURE\n\n```txt\nproject/\n├── controllers/\n│   ├── users/\n│   │   ├── users.routing.js\n│   │   ├── users.action.js\n│   │   └── users.spec.js\n│   ├── cars/\n│   │   ├── cars.routing.js\n│   │   ├── cars.spec.js\n|   |   ├── cars-get.action.js\n│   │   └── cars-post.action.js\n│   └── simple-ctrl.js\n├── core/\n│   └── permissions.js\n├── app.js\n└── package.json\n```\n\n![alt text](https://raw.githubusercontent.com/Alex-Levacher/Lumie/master/images/preview-run.png)\n\n## 🎮 USAGE\n\n### Example: project/controllers/cars.js\n\n```js\nconst postCars = require(\"./cars-post.action\");\nconst getCars = require(\"./cars-get.action\");\n\nmodule.exports = {\n  path: \"awesome-cars\", // rename the path of the route (optional)\n  '/': {\n    post: {\n      middlewares: postCars.middlewares,\n      action: postCars.action,\n      level: 'public'\n    },\n    get: {\n      action: getCars.getAll,\n      level: 'public'\n    }\n  },\n  '/:id': {\n    get: {\n      action: getCars.getOne,\n      level: 'public'\n    }\n  }\n};\n```\n\n```\n'/\u003cname of your route\u003e': {\n        \u003c get | put | delete | post \u003e: {\n            action: \u003c function(req, res) \u003e,\n            level: \u003c parameters of you permission function \u003e, // Optional\n            middlewares: \u003c Array(function(req, res, next)) \u003e// Optional\n        }\n    }\n```\n\n## 🌠 BEST PRACTICES\n\nThere is **2** common way to create a controller with Lumie, you can take a look [here](https://github.com/Alex-Levacher/Lumie/blob/master/example/controllers) to learn how to implement them.\n\n* **Minimal** ([sample](https://github.com/Alex-Levacher/Lumie/blob/master/example/controllers/simple-ctrl.js)): You only create one file which takes as name, the name of the controller you want to create. Then you define the routing definition and the functions. This method is recommended if you plan to have a small controller with few actions.\n* **Structured** ([sample](https://github.com/Alex-Levacher/Lumie/tree/master/example/controllers/users)): You create a new directory with the name of the controller. Inside, you create:\u003cbr\u003e\n  * `[your-controller-name].routing.js` which contains the routing definition\n  * `[your-controller-name].actions.js` which contains the action functions of the controller.\n  * `[your-controller-name].spec.js` This one is optional\n\nIf your controller is pretty heavy, with a lot of functions, we recommend to create one file per action (`create-user.action.js`, `get-user.action.js`, etc… ) ([sample](https://github.com/Alex-Levacher/Lumie/tree/master/example/controllers/cars))\n\n## 🤙 EXAMPLES\n\n* [Simple Lumie project](https://github.com/Alex-Levacher/Lumie/tree/master/example)\n* [Simple controller](https://github.com/Alex-Levacher/Lumie/blob/master/example/controllers/simple-ctrl.js)\n* [Structured controller](https://github.com/Alex-Levacher/Lumie/tree/master/example/controllers/users)\n* [Scalable structured controller](https://github.com/Alex-Levacher/Lumie/tree/master/example/controllers/cars)\n\n## 🚀 ROADMAP\n\nHere are the next features planned, let me know if you have some ideas\n\n* Create a CLI to generate new controllers / projects\n\n## ☕️ SUPPORT\nYou can support the project by\n* Star our GitHub repo ⭐️\n* [Suggest ideas](https://github.com/Alex-Levacher/Lumie/issues) to help me promote Lumie 🌎\n\nIf you are struggling to setup Lumie, you found a bug or if you have some improvement ideas, feel free to [create an issue](https://github.com/Alex-Levacher/Lumie/issues)\u003cbr\u003e\u003cbr\u003e\n\n\n## ⚖️ LICENSE\n\nThis software is licensed under the MIT © [Alex Levacher](mailto:levacher.alex@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-levacher%2Flumie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falex-levacher%2Flumie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falex-levacher%2Flumie/lists"}