{"id":20284865,"url":"https://github.com/allanoricil/nrg-cli","last_synced_at":"2025-04-18T03:10:27.444Z","repository":{"id":255591687,"uuid":"851390012","full_name":"AllanOricil/nrg-cli","owner":"AllanOricil","description":"⚡️ A powerful CLI tool for generating, building, and managing Node-RED nodes and plugins with best practices.","archived":false,"fork":false,"pushed_at":"2025-03-28T06:40:43.000Z","size":918,"stargazers_count":6,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-29T06:13:53.557Z","etag":null,"topics":["builder","cli","node-red","nrg"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/AllanOricil.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2024-09-03T02:27:15.000Z","updated_at":"2025-02-28T16:08:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"e582bb18-6ad6-4e43-92fe-3ea6b18b5b7b","html_url":"https://github.com/AllanOricil/nrg-cli","commit_stats":null,"previous_names":["allanoricil/nrg-cli"],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanOricil%2Fnrg-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanOricil%2Fnrg-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanOricil%2Fnrg-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllanOricil%2Fnrg-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AllanOricil","download_url":"https://codeload.github.com/AllanOricil/nrg-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249418510,"owners_count":21268444,"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":["builder","cli","node-red","nrg"],"created_at":"2024-11-14T14:22:34.742Z","updated_at":"2025-04-18T03:10:27.415Z","avatar_url":"https://github.com/AllanOricil.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/allanoricil"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"nrg-icon\" src=\"https://gist.githubusercontent.com/AllanOricil/84412df273de46b28c5d6945b391afd4/raw/0c9cdb994c40ab3d7b7ad06dcee162145d77d531/nrg-icon.svg\" style=\"width: 200px\"/\u003e\n\u003c/p\u003e\n\u003cbr/\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@allanoricil/nrg-cli\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@allanoricil/nrg-cli.svg\" alt=\"npm package\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/ci.yaml\"\u003e\u003cimg src=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/ci.yaml/badge.svg?branch=main\" alt=\"build status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/windows.yaml\"\u003e\u003cimg src=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/windows.yaml/badge.svg?branch=main\" alt=\"windows integration tests status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/ubuntu.yaml\"\u003e\u003cimg src=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/ubuntu.yaml/badge.svg?branch=main\" alt=\"ubuntu integration tests status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/macos.yaml\"\u003e\u003cimg src=\"https://github.com/AllanOricil/nrg-cli/actions/workflows/macos.yaml/badge.svg?branch=main\" alt=\"macos integration tests status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# ⚡️ nrg - Node-RED Generator\n\n**nrg** (pronounced \"energy\") is a CLI tool designed to empower Node-RED developers with speed and efficiency. The name **nrg** stands for **Node-RED Generator**, but it's pronounced like \"energy\" to symbolize the power and momentum it brings to your workflow. Just as energy drives systems forward, **nrg** accelerates your development process, helping you quickly generate, build, and manage Node-RED nodes and plugins. Whether you're building simple automations or complex integrations, **nrg** ensures that you can focus your energy on writing meaningful code, while it takes care of the setup and scaffolding.\n\nClearly, the best model to write nodes for Node-RED.\n\n## 💡 Examples\n\n| Name                          | Repository                                                   |\n| ----------------------------- | ------------------------------------------------------------ |\n| nrg-template                  | https://github.com/AllanOricil/nrg-template                  |\n| node-red-oidc-provider        | https://github.com/AllanOricil/node-red-oidc-provider        |\n| node-red-salesforce           | https://github.com/AllanOricil/node-red-salesforce           |\n| node-red-spreadsheet-template | https://github.com/AllanOricil/node-red-spreadsheet-template |\n\n## 🛠️ Integrated Toolchain\n\nThis CLI comes with a set of embedded tools to streamline your development workflow. These tools are preconfigured to handle common tasks such as bundling, transpiling, and optimizing assets, so you can focus on building your project without manual setup.\n\n- [esbuild](https://github.com/AllanOricil/nrg/blob/e68363270c09a183a26bdfb8580b30fd2e74c7fd/package.json#L58): A fast and highly efficient JavaScript bundler and minifier.\n- [postcss](https://github.com/AllanOricil/nrg/blob/e68363270c09a183a26bdfb8580b30fd2e74c7fd/package.json#L67): A powerful tool for transforming CSS with plugins, enabling features like autoprefixing, nesting, and custom properties.\n- [html-minifier-terser](https://github.com/AllanOricil/nrg/blob/e68363270c09a183a26bdfb8580b30fd2e74c7fd/package.json#L62): A tool to minify and optimize HTML files, reducing file size for faster loading times.\n\nThese integrated tools help ensure your code is optimized and production-ready with minimal configuration.\n\n\u003e [!NOTE]\n\u003e\n\u003e In the future, [esbuild](https://esbuild.github.io/) will be replaced by [rolldown](https://rolldown.rs/)\n\n## ✨ Commands\n\n\u003e [!WARNING]\n\u003e\n\u003e [Sentry](https://sentry.io/) is used to collect metrics, traces and errors while running the CLI. Read more about it in the [Telemetry](#-telemetry) section of this document.\n\n### ⬛ `nrg build`\n\nThe `nrg build` command compiles and packages your Node-RED nodes or plugins, ensuring everything is bundled and ready for deployment.\n\n```bash\nnrg build\n```\n\nUse this command when you're ready to build your project for production. The default settings used to bundle your javascript can be found\n[here](https://github.com/AllanOricil/nrg/blob/main/defaults/nrg.json). You can override any of those properties for both `prod` and `dev` builds.\n\n### ⬛ `nrg dev`\n\nThe nrg dev command starts a development environment for your Node-RED project. This allows you to iterate quickly, testing changes in real-time as you build.\n\n```bash\nnrg dev\n```\n\nUse this command to work interactively on your custom nodes or plugins, making development faster and smoother. As mentioned before, the default settings used to bundle your javascript can be found [here](https://github.com/AllanOricil/nrg/blob/main/defaults/nrg.json), and you can override any of these properties changing `build.dev.server` or `build.dev.client`.\n\nIn order to run a `prod` build locally, use the following command `nrg dev -o -e prod`.\n\n### ⬛ `nrg create`\n\nUse this command to create an nrg project with ease.\n\n```bash\nnrg create -n \u003cproject-name\u003e\n```\n\n### ⬛ `nrg create node`\n\nUse this command to create node-red nodes for an nrg project.\n\n```bash\nnrg create node -n \u003cnode-name\u003e\n```\n\nFor more details about `nrg` commands, run\n\n```bash\nnrg --help\n```\n\n## 🗂️ Base Project Directory Structure\n\n```bash\nmy-custom-nodes/\n├── package.json\n├── nrg.config.js\n└── src/\n    └── nodes/\n        └── node-type/\n            ├── client/\n            │   ├── locales/\n            │   │   ├── labels/\n            │   │   │   ├── de.json\n            │   │   │   └── en-US.json\n            │   │   └── docs/\n            │   │       ├── de.html\n            │   │       └── en-US.html\n            │   ├── icons/\n            │   │   └── icon-1.png\n            │   ├── stylesheet.scss\n            │   ├── index.html\n            │   └── index.js\n            └── server/\n                └── index.js\n```\n\n| Folder      | Description                                                                                                                                                                                                                                                                                        | Required |\n| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |\n| nodes       | It is where all nodes must be located                                                                                                                                                                                                                                                              | ✅       |\n| {node-type} | It is the name used by node-red to uniquely identify the type of your node. It is used in many places by the builder, such as to register your node using `RED.nodes.registerType(\"{node-type\")`, or when generating boilerplate code for docs `\u003cscript type=\"text/html\" data-type=\"{node-type\"}\u003e` | ✅       |\n| client      | Use this directory to store the assets shown in the editor: locales, icons, stylesheets, html and javascript.                                                                                                                                                                                      | ✅       |\n| locales     | Use this directory to store docs and labels.                                                                                                                                                                                                                                                       |          |\n| labels      | Use this directory to store your labels as .json files. Labels are scoped by the node's type, and they can be retrieved at runtime with `this._(\"{node-type}.label\")` or `RED._(\"{node-type}.label\")`                                                                                              |          |\n| docs        | Use this directory to store your html docs.                                                                                                                                                                                                                                                        |          |\n| icons       | Use this directory to store the icons.                                                                                                                                                                                                                                                             |          |\n| server      | Use this directory to write the server side javascript of your node.                                                                                                                                                                                                                               | ✅       |\n\n### Client Entrypoint\n\nThe client entrypoint must be named as `index.js`, and it must export a default object as follows:\n\n```js\nexport default {\n  category: \"custom nodes\",\n  color: \"#FFFFFF\",\n  defaults: {\n    name: { value: \"\" },\n  },\n  inputs: 1,\n  outputs: 1,\n  icon: \"icon-3.png\",\n  align: \"left\",\n  paletteLabel: function () {\n    return this.name || this._(\"node-3.name\") || \"node-3\";\n  },\n  label: function () {\n    return this.name || this._(\"node-3.name\") || \"node-3\";\n  },\n  oneditprepare: function () {},\n  oneditcancel: function () {},\n  oneditdelete: function () {},\n};\n```\n\nAvailable properties can be found in this Node-RED [doc](https://nodered.org/docs/creating-nodes/node-html#node-definition).\n\n### Server Entrypoint\n\nThe server entrypoint must be named as `index.js`, and it must export a default class as follows:\n\n```js\nimport { Node } from \"@allanoricil/nrg-nodes\";\n\nexport default class Node1 extends Node {\n  // NOTE: executed every time an instance of your node is created\n  constructor(config) {\n    super(config);\n  }\n\n  // NOTE: executed once, when the type is registered\n  static init() {}\n\n  // NOTE: use it if your node has settings\n  static settings() {}\n\n  // NOTE: use it if your node stores credentials\n  static credentials() {}\n\n  // NOTE: it can be async. You don't need to call this.on(\"input\") anymore\n  onInput(msg, send, done) {}\n\n  // NOTE: it can be async. You don't need to call this.on(\"close\") anymore\n  onClose(removed, done) {}\n}\n```\n\nAll available methods can be found [here](https://github.com/AllanOricil/node-red-node/blob/main/src/node.js).\n\n#### `static settings`\n\nUse this method to configure custom settings for your node. It must return an object as follows:\n\n```js\nstatic settings(){\n\treturn {\n\t\texampleSetting: {\n\t\t\tvalue: \"default\",\n\t\t\texportable: true\n\t\t}\n\t}\n}\n```\n\nThe `exampleSetting` attribute shown above will be accessible in the editor, and server, as `RED.settings.myNodeExampleSetting`, where `my-node` is the Node's type. Read more about it in this Node-RED [doc](https://nodered.org/docs/creating-nodes/node-js#custom-node-settings).\n\n#### `static credentials`\n\nUse this method to configure the credentials available to your node. It must return an object as follows:\n\n```js\nstatic credentials(){\n\treturn {\n\t\tusername: { type:\"text\" },\n\t\tpassword: { type:\"password\" }\n\t}\n}\n```\n\nRead more about it in this Node-RED [doc](https://nodered.org/docs/creating-nodes/credentials).\n\n#### Context\n\nInside the Node's class, you can access context stores as follows:\n\n```js\n// NOTE: Node's context\nthis.context().get(\"key\");\nthis.context().set(\"key\", value);\n\n// NOTE: Flow context\nthis.flowContext.get(\"key\");\nthis.flowContext.set(\"key\", value);\n\n// NOTE: Global context\nthis.globalContext.get(\"key\");\nthis.globalContext.set(\"key\", value);\n```\n\nRead more aobut it in this Node-RED [doc](https://nodered.org/docs/creating-nodes/context).\n\n## ⚙️ Configuration File\n\nIn the root of an `nrg` project, there must exist a config file. This config must be any of the following formats:\n\n```base\n.nrgrc.json\n.nrgrc.js\n.nrgrc.cjs\nnrg.config.json\nnrg.config.js\nnrg.config.cjs\n.config/nrgrc\n.config/nrg.json\n.config/nrg.js\n.config/nrg.cjs\n```\n\nYou can also choose to have an `nrg` object in the root of your `package.json`.\n\nThese are all the properties you can configure:\n\n```js\nmodule.exports = {\n  version: \"0.0.0\", // controls the schema version of the config file.\n  dev: {\n    watch: {\n      paths: [], // additional paths that will trigger a rebuild\n    },\n  },\n  build: {\n    environment: \"prod\", // it can be either prod or dev. If absent, it defaults to prod.\n    server: {\n      // global esbuild settings. Use it to override both prod and dev build settings\n    },\n    client: {\n      // global esbuild settings. Use it to override both prod and dev build settings\n    },\n    dev: {\n      // dev build settings\n      server: {\n        // esbuild settings used to build the server side javascript of your node\n      },\n      client: {\n        // esbuild settings used to build the client side javascript of your node\n      },\n    },\n    prod: {\n      // prod build settings\n      server: {\n        // esbuild settings used to build the server side javascript of your node\n      },\n      client: {\n        // esbuild settings used to build the client side javascript of your node\n      },\n    },\n  },\n  nodeRed: {}, // Node-RED settings properties that are used when node-red is started\n};\n```\n\nThe javascript is processed by `esbuild`. You can use any `esbuild` settings, including plugins. To find a complete list of properties `esbuild` has, read their [doc](https://esbuild.github.io/api/#general-options). To use a plugin, make sure your config file is either `.js` or `.cjs`, and that it exports seetings as shown below. For example, the following `nrg.config.js` is using the `esbuild-vue` plugin to build vue components.\n\n```js\nconst vuePlugin = require(\"esbuild-vue\");\n\nmodule.exports = {\n  version: \"0.0.0\",\n  build: {\n    client: {\n      plugins: [\n        vuePlugin({\n          production: true,\n        }),\n      ],\n    },\n  },\n};\n```\n\nAll Node-RED settings that you can use with `nodeRed` can be found in this Node-RED [doc](https://nodered.org/docs/user-guide/runtime/configuration).\n\n## 📦 `package.json`\n\nBelow is the bare minimum `package.json` configuration. Attention for the `node-red.nodes.nodes` property. It must be `dist/index.js`, which is the entrypoint of the build that is located in the `dist` folder. In the future you won't need to setup this by hand.\n\n```json\n{\n  \"name\": \"package-name\",\n  \"version\": \"0.0.0\",\n  \"description\": \"Package description\",\n  \"engines\": {\n    \"node\": \"\u003e=18\",\n    \"npm\": \"\u003e=10\"\n  },\n  \"scripts\": {\n    \"build\": \"nrg build\",\n    \"build:dev\": \"nrg build -e dev\",\n    \"watch\": \"nrg dev -w -o\",\n    \"watch:debug\": \"nrg dev -w -o -d\",\n    \"start\": \"nrg dev -o\",\n    \"start:debug\": \"nrg dev -o -d\",\n    \"start:prod\": \"nrg dev -o -d -e prod\"\n  },\n  \"node-red\": {\n    \"version\": \"\u003e=3.1\",\n    \"nodes\": {\n      \"nodes\": \"dist/index.js\"\n    }\n  },\n  \"dependencies\": {},\n  \"devDependencies\": {\n    \"@allanoricil/nrg-cli\": \"2.0.0\"\n  }\n}\n```\n\nThe cli must be added as a dev dependency because it has the following peer dependencies `@allanoricil/node-red-node` and `node-red` , which must be available in the working directory, inside the `node_modules` directory, at the moment of the build.\n\n## 🔮 Upcomming Features\n\nHere’s a sneak peek at what's coming, once the aforementioned commands are stable.\n\n### ⬛ `nrg create plugin`\n\nFor more complex use cases, this command will generate a plugin structure for Node-RED, setting up everything you need to build advanced functionality.\n\n```bash\nnrg create plugin \u003cplugin-name\u003e\n```\n\n### ⬛ `nrg create node --type widget`\n\nThis command will generate a node for dashboard 2.0.\n\n```bash\nnrg create node --type widget \u003cnode-name\u003e\n```\n\n## ⬇️ Installation\n\nTo get started with nrg, install it as a dev dependency on your `nrg` project, using npm:\n\n```bash\nnpm install @allanoricil/nrg-cli -D\n```\n\nYou can also install it globally, using the following command\n\n```bash\nnpm install @allanoricil/nrg-cli -g\n```\n\n## 📊 Telemetry\n\nThis project uses [Sentry](https://sentry.io/) to collect anonymous telemetry data to help improve the CLI tool's functionality and user experience. Below is an outline of what data is collected:\n\n### What Data is Collected?\n\n- **Commands Executed**: The specific CLI commands that are run.\n- **Command Arguments**: The arguments passed to the CLI commands (excluding sensitive information like passwords, API keys, or other personal data).\n- **Errors and Exceptions**: If a command encounters an error or exception, details about the error (such as stack traces) are captured to aid in debugging and improving the tool.\n\n### How is the Data Used?\n\n- **Improving Features**: Understanding which commands and options are used most frequently helps prioritize new features and updates.\n- **Debugging**: Error reports assist in identifying bugs and ensuring the tool works smoothly.\n- **Performance Monitoring**: Sentry allows us to monitor the performance of the CLI to ensure it is efficient and responsive.\n\n### Data Privacy\n\n- **No Personal Information**: We do not collect any personally identifiable information (PII). Sensitive data like passwords, tokens, or confidential user input is never collected or logged.\n- **Anonymized Data**: All telemetry data is anonymous and used only for the purposes outlined above.\n\n### Opting Out\n\nIf you prefer not to send telemetry data, you can disable it by setting an environment variable:\n\n```bash\nexport NRG_DISABLE_TELEMETRY=true\n```\n\nAlternatively, you can use the `--no-telemetry` flag with each command to disable telemetry.\n\n## 🤝 Contributing\n\nI welcome contributions! If you'd like to help improve nrg, feel free to open issues or submit pull requests. Your feedback is appreciated.\n\n## 📜 License\n\nThis project is licensed under the [MIT License](https://github.com/AllanOricil/nrg-cli/blob/main/LICENSE).\n\n## 💖 Become a Sponsor\n\nIf this CLI has made your life easier, consider supporting its development by clicking the button below.\n\n\u003ca href=\"https://www.buymeacoffee.com/allanoricil\" target=\"_blank\"\u003e\n  \u003cimg\n      src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\"\n      alt=\"Buy Me A Coffee\"\n      style=\"width: 217px;\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallanoricil%2Fnrg-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallanoricil%2Fnrg-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallanoricil%2Fnrg-cli/lists"}