{"id":30076549,"url":"https://github.com/shadowmoose/node-config-panel","last_synced_at":"2026-02-03T01:25:28.662Z","repository":{"id":304104893,"uuid":"1017749154","full_name":"shadowmoose/node-config-panel","owner":"shadowmoose","description":"Configuration GUI for Node/Bun.","archived":false,"fork":false,"pushed_at":"2025-08-05T18:45:17.000Z","size":305,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T18:53:29.671Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/shadowmoose.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-07-11T03:32:53.000Z","updated_at":"2025-08-05T18:44:00.000Z","dependencies_parsed_at":"2025-07-11T08:57:04.451Z","dependency_job_id":"b4d85e1d-0083-4ec9-b13e-5d35b62e79e3","html_url":"https://github.com/shadowmoose/node-config-panel","commit_stats":null,"previous_names":["shadowmoose/node-config-panel"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/shadowmoose/node-config-panel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowmoose%2Fnode-config-panel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowmoose%2Fnode-config-panel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowmoose%2Fnode-config-panel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowmoose%2Fnode-config-panel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shadowmoose","download_url":"https://codeload.github.com/shadowmoose/node-config-panel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowmoose%2Fnode-config-panel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269447935,"owners_count":24418756,"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-08-08T02:00:09.200Z","response_time":72,"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":[],"created_at":"2025-08-08T15:57:32.729Z","updated_at":"2026-01-20T17:36:55.848Z","avatar_url":"https://github.com/shadowmoose.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![NPM Version](https://img.shields.io/npm/v/%40shadowmoose%2Fconfig)](https://npmjs.com/package/@shadowmoose/config)\n[![Static Badge](https://img.shields.io/badge/docs-8A2BE2)](https://shadowmoose.github.io/node-config-panel/latest)\n\n\n# Config Panel\nThis is my personal configuration library, used primarily for rapid development of desktop Node/Bun apps.\nBecause most others weren't type-safe enough for my liking: \nAt last, a config library where ctrl+clicking actually takes you to the definition.\n\nThis low-dependency library provides all the usual config parsing\n(environment, JSON files, and arguments), and also bundles a web-based configuration panel that \noffers an interactive experience to expose even the most complex configuration options to users in a friendly way.\n\nAll configuration values are strongly typed, and validated before being accepted.\nThis means that even without the GUI, \nthe data parsed by this library is more reliable and easier to work with than most other packages.\n\nBecause it is web-based, the config panel also offers support for long-running remote configuration.\nBasic display capabilities are included, allowing apps to display any data they wish within the UI, \nupdating live. Don't like the stock UI? No problem, you can customize it with your own CSS and HTML.\n\nFetch the latest valid configuration values whenever you want, readily exposed as a simple object,\nor listen for changes to specific values as they happen.\n\nThe UI even has support for non-configuration elements that nonetheless operate live,\nsuch as buttons and HTML data displays.\n\n[![screenshot](docs/screenshot.png)](docs/screenshot.png)\n\n\u003e **Note:**  \n\u003e The UI pictured above can be customized to your liking via CSS\n\u003e \n## What data does it support?\nAnything you can model in Zod, and potentially more.\n\nOut of the box, the library has strong support for:\n+ Standard text/number/boolean primitives.\n+ Enums, with strongly-typed unions passed all the way through.\n+ Arrays, including complex validation on each item.\n+ Anything JSON serializable.\n\nThe library also offers first-class support for custom Zod schemas and matching HTML elements, \nwhich can be used to model essentially anything.\n\n## Installation\n```npm i @shadowmoose/config```\n\n[Check out the Documentation](https://shadowmoose.github.io/node-config-panel/latest) for more details.\n\n## Example Usage\nHere's a long-winded example showcasing many of the supported features.\n```typescript\nimport { ConfigPanel, InputType, Elements } from \"@shadowmoose/config\";\n\n// Define a new configuration panel with strong types.\nconst config = new ConfigPanel({\n    // Define categories.\n    first_category: { displayName: 'Test Category', description: 'This is a test category' },\n    cat_2: { displayName: 'Category Two' },\n}, {\n    // Define all config inputs, within each category.\n    first_category: {\n        text_string: {\n            type: InputType.string().max(20).default('test-default'), // Input types are just Zod schemas.\n            displayName: 'Text String',\n            description: 'A simple text string input',\n        },\n        test_number: {\n            type: InputType.number().min(0).max(100).refine(value =\u003e value % 2 === 0, 'Number must be even'),\n            displayName: 'Test Number',\n        },\n        test_boolean: {\n            type: InputType.boolean().default(false),\n            displayName: 'Test Boolean',\n            description: 'Check me out.'\n        },\n    },\n    cat_2: {\n        test_enum: {\n            type: InputType.enum([\"Salmon\", \"Tuna\", \"Trout\"]).default('Tuna'),\n            envName: 'FISH_TYPE', // Custom environment variable name.\n        },\n        complex_string_array: {\n            type: z.string().transform(value =\u003e value.split(',')).pipe(z.string().trim().min(1).array()),\n            default: 'one,two,three', // Example transform from CSV into Array.\n            useZodTypeName: 'string', // Render as a string input to the user.\n        },\n        btn_test: Elements.Button({\n            text: 'Click Me!', // Example button that temporarily disables itself when clicked.\n            onClick: (_path) =\u003e {\n                // Clicks are also emitted as events, so you could listen for it instead of using this callback.\n                console.log('Button clicked!');\n                conf.setEnabled('cat_2', 'btn_test', false); // All inputs are strongly typed.\n                setTimeout(() =\u003e conf.setEnabled('cat_2', 'btn_test', true), 2_000);\n            },\n        })\n    }\n});\n\n// Example: Load existing config from a JSON file and environment variables, then start the interface.\n// All values are optional.\nawait config\n    .fromJSON({\n        filePath: '.env.json', // Load existing config from a JSON file, if it exists.\n    }).fromEnvironment({\n        prefix: 'TEST_', // Load existing config from environment variables, with optional prefix.\n        envFile: '.env',\n    }).startInterface({\n        title: 'Test Config Panel',\n        displayMethod: 'browser', // 'browser' | 'none'\n        port: 0, // Use random available port.\n        host: '0.0.0.0', // Bind to all interfaces to allow remote access.\n        // Optional custom CSS/HTML to apply to the panel. Everything has simple class names to make this easy.\n        style: '.category_title { color: blue; } .wrapper_first_category { background: #f0f0f0 !important; }',\n        htmlHeader: '\u003ch1 style=\"text-align: center\"\u003eConfiguration Panel\u003c/h1\u003e',\n        htmlFooter: '\u003cp style=\"font-size: small;text-align: center\"\u003eGenerated Panel Demo\u003c/p\u003e',\n    });\n\n// Example: save updated config to a JSON file.\nconfig.toJSON('.env.json');\n// Example: accessing current valid config values live, without waiting.\nconsole.log(config.values);\n/* Output: {\n    first_category: {\n        text_string: string\n        test_number: number\n        test_boolean: boolean\n    }\n    cat_2: {\n        test_enum: \"Salmon\" | \"Tuna\" | \"Trout\",\n        complex_string_array: string[]\n    }\n} */\n\n// Wait for the panel to be closed, and save the results to a variable.\nconst results = await config.waitForClose();\nconsole.log('Configured enum value:', results.cat_2.test_enum);\n// Output: 'Configured enum value: Tuna'\n```\n\n## Event-Driven Updates\nAll data updates are emitted as events, enabling real-time feedback and dynamic behavior if desired.\nUsing the above example `config`, you can listen for events like so:\n```typescript\nconfig.on('values', console.dir); // Listen for changes to any values.\nconfig.on('change.first_category', console.dir); // Changes to values within a specific category. Strongly typed.\nconfig.on(config.getChangeKey('test_cat', 'test_number'), console.log); // Changes to a specific value. Strongly typed.\nconfig.on('error', console.error); // Listen for any errors that occur.\nconfig.on('exit', console.error); // Listen for when the panel is closed.\n```\n\n## Data Visualization\nThe library also supports sending data to the UI, for display or interaction.\nHere's some example code that updates the UI every second with a timer.\n```typescript\nsetInterval(() =\u003e {\n    config.sendHTML('first_category', `\u003ch3\u003eCurrent Time: ${new Date().toLocaleTimeString()}\u003c/h3\u003e`);\n}, 1_000); // Update every second.\n```\n\nAll value references are preserved and updated as well, so accessing the latest values in the above example without implementing event logic is as simple as:\n```\nresults.cat_2.test_enum\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowmoose%2Fnode-config-panel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshadowmoose%2Fnode-config-panel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowmoose%2Fnode-config-panel/lists"}