{"id":26126222,"url":"https://github.com/discoveryjs/discovery-cli","last_synced_at":"2025-04-13T16:11:29.643Z","repository":{"id":35103820,"uuid":"207181186","full_name":"discoveryjs/discovery-cli","owner":"discoveryjs","description":"CLI tools to serve \u0026 build projects based on Discovery.js","archived":false,"fork":false,"pushed_at":"2025-03-22T01:40:35.000Z","size":1502,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T17:25:04.536Z","etag":null,"topics":["cli","discoveryjs","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/discoveryjs.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":"2019-09-08T22:24:55.000Z","updated_at":"2025-03-22T01:38:05.000Z","dependencies_parsed_at":"2023-02-10T23:31:20.505Z","dependency_job_id":"463948e8-1518-4e88-9d8a-2bedd5ccbc01","html_url":"https://github.com/discoveryjs/discovery-cli","commit_stats":{"total_commits":399,"total_committers":4,"mean_commits":99.75,"dds":0.1127819548872181,"last_synced_commit":"acf06f096710757a7b9d7722b5d7a4e9a8ee35f1"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoveryjs%2Fdiscovery-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoveryjs%2Fdiscovery-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoveryjs%2Fdiscovery-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/discoveryjs%2Fdiscovery-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/discoveryjs","download_url":"https://codeload.github.com/discoveryjs/discovery-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741197,"owners_count":21154255,"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":["cli","discoveryjs","nodejs"],"created_at":"2025-03-10T17:28:26.414Z","updated_at":"2025-04-13T16:11:29.636Z","avatar_url":"https://github.com/discoveryjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"right\" width=\"128\" height=\"128\"\n     alt=\"Discovery.js project logo\"\n     src=\"https://user-images.githubusercontent.com/270491/48985803-1563ae80-f11d-11e8-92c0-e07fbf0bcd94.png\"/\u003e\n\n# Tools for Discovery.js\n\n[![NPM version](https://img.shields.io/npm/v/@discoveryjs/cli.svg)](https://www.npmjs.com/package/@discoveryjs/cli)\n[![Twitter](https://badgen.net/badge/follow/@js_discovery?icon=twitter)](https://twitter.com/js_discovery)\n\nCLI tools to serve \u0026 build projects based on [Discovery.js](https://github.com/discoveryjs/discovery)\n\n\u003c!-- TOC depthfrom:2 --\u003e\n\n- [Install](#install)\n- [Commands](#commands)\n    - [discovery (serve)](#discovery-serve)\n    - [discovery-build (build)](#discovery-build-build)\n- [Modes](#modes)\n    - [Single model](#single-model)\n    - [Multiple models](#multiple-models)\n    - [Model-free](#model-free)\n- [Configuration](#configuration)\n    - [Model config](#model-config)\n    - [Multi-model config](#multi-model-config)\n    - [Configure view](#configure-view)\n- [License](#license)\n\n\u003c!-- /TOC --\u003e\n\n## Install\n\n```\nnpm install @discoveryjs/cli\n```\n\n## Commands\n\n### discovery (serve)\n\n```\nUsage:\n\n    discovery [config] [options]\n\nOptions:\n\n        --bail                    Exit immediately on first warmup task failure\n        --no-bg-update            Disable background data cache updates\n        --no-cache                Disable data caching\n        --cache-persistent        Use persistent caches system\n        --cachedir [dir]          Path to store cache files (using .discoveryjs-cache by default when\n                                  [dir] is not set)\n        --no-check-cache-ttl      Disable data cache TTL checking before using it\n    -c, --config \u003cfilename\u003e       Path to config (JavaScript or JSON file), if not specified then looking\n                                  for .discoveryrc.js, .discoveryrc.json, .discoveryrc or \"discovery\"\n                                  section in package.json in the listed order\n        --cors                    Enable CORS, i.e. allows data fetching for any origin\n        --no-dev                  Disable using Discovery.js \"src\" assets when available (disables\n                                  discovery-dev condition)\n        --embed [mode]            Specify an embed API: by-config (default), enable (when [mode] omitted)\n                                  or disable\n        --experimental-jsonxl     Enable experimental binary data encoding (codename JSONXL)\n    -h, --help                    Output usage information\n        --no-minify               Disable JS and CSS minification\n    -m, --model \u003cname\u003e            Specify a model (multi-model mode only)\n        --no-model-data-upload    Disable model data upload feature\n        --no-model-download       Disable model download feature\n        --no-model-reset-cache    Disable model cache reset feature\n    -p, --port \u003cn\u003e                Listening port (default: 8123)\n        --prebuild [path]         Prebuild model's static in path (path is optional, `build` by default)\n        --tmpdir \u003cdir\u003e            Path to directory of temporary cache files which are generating before\n                                  committing to cache directory\n    -v, --version                 Output version\n        --no-warmup               Disable model's data cache warm up on server start\n```\n\nTo create and launch a server in your script, use `createServer()` method which returns [`express`'s application](https://expressjs.com/en/api.html#app):\n\n```js\nconst discovery = require('@discoveryjs/cli');\nconst PORT = 1234;\n\ndiscovery.createServer({ /* options */ }).listen(PORT, function() {\n    console.log(`Server listen on http://localhost:${this.address().port}`);\n});\n```\n\n### discovery-build (build)\n\n```\nUsage:\n\n    discovery-build [config] [options]\n\nOptions:\n\n        --asset-names [pattern]         Pattern for file names of the asset files corresponding to each model\n        --no-cache                      Disable data caching\n        --cachedir [dir]                Path to store cache files (using .discoveryjs-cache by default when [dir]\n                                        is not set)\n        --check-cache-ttl               Check data cache TTL before using it, option enforces to use actual\n                                        (according to TTL) data only\n        --clean                         Clean the output directory before emit a build files\n    -c, --config \u003cfilename\u003e             Path to config (JavaScript or JSON file), if not specified then looking\n                                        for .discoveryrc.js, .discoveryrc.json, .discoveryrc or \"discovery\"\n                                        section in package.json in the listed order\n        --no-data                       Don't include data into a model build\n        --no-data-compression           Disable HTML embedded data compression, when --single-file option is used\n        --no-dev                        Disable using Discovery.js \"src\" assets when available (disables\n                                        discovery-dev condition)\n        --embed [mode]                  Specify an embed API: by-config (default), enable (when [mode] omitted)\n                                        or disable\n        --entry-names [pattern]         Pattern for file names of the output HTML files corresponding to each model\n        --exclude-model-on-data-fail    Exclude models from the result if their data generation fails, ignoring\n                                        the failure instead of halting the build (exit code: 1)\n        --experimental-jsonxl           Enable experimental binary data encoding (codename JSONXL)\n    -h, --help                          Output usage information\n        --no-minify                     Disable JS and CSS minification\n    -m, --model \u003cname\u003e                  Specify a model (multi-model mode only)\n        --no-model-data-upload          Ignore model data upload feature setup in config\n        --model-download                Enable model download feature\n        --model-reset-cache             Enable model cache reset feature\n    -o, --output \u003cpath\u003e                 Path for a build result (`build` by default)\n        --pretty-data [indent]          Pretty print of model data if any\n        --script-external [pattern]     Mark a file or a package as external to exclude it from script bundle\n                                        (see https://esbuild.github.io/api/#external). Use \"all\" value (without\n                                        quotes, a shorthand for \"./node_modules/*\") to disable all the npm\n                                        packages from the bundle\n        --script-format [format]        Output format for the script files: esm (default), cjs or both\n        --script-names [pattern]        Pattern for file names of the script files corresponding to each model\n        --serve-only-assets             Include server only assets into build\n    -s, --single-file                   Output a model build as a single HTML file per model\n        --single-file-data [side]       Used to specify where to locate data: external (default), inline (default\n                                        when --single-file is used), both\n        --sourcemap [mode]              Enable source map generation, optional \"mode\" can be: linked (default,\n                                        when [mode] is omitted), external or inline\n                                        (see https://esbuild.github.io/api/#sourcemap for detail)\n        --tmpdir \u003cdir\u003e                  Path to directory of temporary cache files which are generating before\n                                        committing to cache directory\n    -v, --version                       Output version\n```\n\n## Modes\n\nDiscovery CLI allows to define a single or multiple predefined models. A model is a composition of data fetch script, prepare data function and a set of pages, views and other helpers. All parts of the model are optional. CLI commands may work in following modes depending on config (see [Configuration](#configuration)):\n\n* `single` – a single model mode, when no index page involved. Enables when config have no `models` field, or `--model` option is used;\n* `multi` – multiple models mode, a set of models and index page that lists models. Enables when config contains `models` field and no `--model` option is used;\n* `modlefree` – model free mode, when no any model is specified. Enables when no config is specified\n\n### Single model\n\nThis mode uses when you need to serve or to build just a single model. To enable this mode, your config must no contain `models` field or command should be lauched with `--model` option (i.e. `discovery --model model-slug`). In this mode the root route will lead to model's default page.\n\n### Multiple models\n\nIn case multiple model should be served by a single service, you may use multi models mode. To activate this mode, the config must contain `models` field, which defines configuration for each model. In this mode discovery will show model selection page as index page. Every model will have its own route namespace (i.e. `slug`), and you can switch between models and index page.\n\n### Model-free\n\nIn this mode there is no any predefined models. However, you can upload any data by clicking \"Load data\" button, or drag'n'drop file right into the browser and discover it. This mode uses when no config file is found.\n\n## Configuration\n\nConfiguration files are supported in several formats (only one will be used in the priority listed below):\n\n* `.discoveryrc.js` (JavaScript)\n* `.discoveryrc.json` (JSON)\n* `.discoveryrc` (the same as `.discoveryrc.json`)\n* `discovery` property in `package.json` (JSON)\n\nThe config file can be explicitly specified by `--config` option. When the config is not found, `modelfree` mode is using.\n\n### Model config\n\nModel config consists of the following fields (all fields are optional):\n\n* `name` – name of the model (used in title)\n* `version` – version of the model, can be used in app header when specified\n* `description` – description of the model, can be used in app header when specified\n* `icon` – path to icon image of the model, can be used in app header when specified\n* `meta` – any data (should be serializable to JSON) that will be available in model's `setup.js`\n* `data` – function which returns `any | Promise\u003cany\u003e` or path to a module (CommonJS or ESM) that exports such a function as default. Result of the function is using for a model; must be serializable to JSON (i.e. have no cyclic references for now)\n* `encodings` – path to a module that exposes an array of encoding configurations for transforming payload data on loading into JavaScript values. This option has an effect only if supported by Discovery.js (added in version `1.0.0-beta.83`).\n* `prepare` – (deprecated, use `setup` instead) path to a module (CommonJS or ESM) with a default export of a function that invokes right after data is loaded but before is used (e.g. add cyclic references and relations in data, mark data objects, add annotations and/or helpers for query engine etc)\n* `setup` – path to a module (CommonJS or ESM) with a function which call on model creation after all the extensions are applied\n* `favicon` – path to favicon image; inherits from parent config when not set\n* `viewport` – value for `\u003cmeta name=\"viewport\"\u003e`; inherits from parent config when not set\n* `darkmode` – setup darkmode feature; inherits from parent config when not set\n* `upload` – settings for upload data feature; inherits from parent config when not set\n* `embed` – explicitly enable or disable embed feature (default `false`)\n* `download` – default value for download feature; inherits from parent config when not set\n* `view` – setup model's views (see [Configure view](#configure-view))\n* `routers` – an array of paths to modules which exports a function (`function(router, modelConfig, options): void`) that extends model router\n* `cache` – enables caching for data\n* `cacheTtl` – specify time to live of data cache. When data cache become too old, new data will be generated on next request. Value might be a number (milliseconds) or a string (e.g. `\"1m\"`, `\"1 hour 30 mins\"` etc; see [parse-duration](https://www.npmjs.com/package/parse-duration) description for possible values)\n* `cacheBgUpdate` – specify a time period from a moment of previous cache was generated to update it. Once new cache is generated, it will be used for upcoming requests. Value might be a number (milliseconds) or a string (e.g. `\"1m\"`, `\"1 hour 30 mins\"` etc; see [parse-duration](https://www.npmjs.com/package/parse-duration) description for possible values)\n\nExample:\n\n```js\nconst path = require('path');\n\nmodule.exports = {\n    name: 'My dashboard',\n    data: './path/to/generate-data-script.js',\n    encodings: path.join(__dirname, 'path/to/encodings.js'),\n    prepare: path.join(__dirname, 'path/to/prepare.js'),\n    favicon: './path/to/favicon.png',\n    viewport: 'width=device-width, initial-scale=1',\n    view: {\n        basedir: __dirname,\n        assets: [\n            './ui/page/default.js',\n            './ui/view/model-custom-view.css',\n            './ui/view/model-custom-view.js',\n            './ui/sidebar.css',\n            './ui/sidebar.js'\n        ]\n    }\n};\n```\n\n### Multi-model config\n\nMultiple models are combine with a single entry point, a config which defines setup for the index page, models and their base configuration. Config should provide JSON or exports an object with following properties (all are optional):\n\n* `name` - name of discovery instance (used in page title)\n* `version` – version for the index page, can be used in app header when specified\n* `description` – description for the index page, can be used in app header when specified\n* `icon` – path to icon image for the index page\n* `models` - object with model configurations, where for each entry the key used as a slug and the value as a config\n* `modelBaseConfig` – the same as model's config, using as a base for a model config, i.e. `{ ...modelBaseConfig, ...modelConfig }` will be used\n* `encodings` – path to a module that exposes an array of encoding configurations for transforming payload data on loading into JavaScript values. This option has an effect only if supported by Discovery.js (added in version `1.0.0-beta.83`).\n* `routers` – an array of paths to modules which exports a function (`function(router, modelConfig, options): void`) that extends app routers\n* `favicon` – path to favicon image\n* `viewport` – value for `\u003cmeta name=\"viewport\"\u003e`\n* `darkmode` – setup darkmode feature (default `\"auto\"`)\n* `upload` – default value for upload data feature (default `false`)\n* `embed` – explicitly enable or disable embed feature (default `false`)\n* `download` – default value for download feature (default `true`)\n* `view` – setup index page views (see [Configure view](#configure-view))\n\nExample:\n\n```js\nmodule.exports = {\n    name: 'Dashboards hub',\n    favicon: './path/to/favicon.png',\n    models: {\n        one: './path/to/model/config',\n        two: require('./path/to/model/config'),\n        three: { /* model config */ }\n    }\n};\n```\n\n### Configure view\n\n* `basedir` – directory to resolve relative paths\n* `assets` – array of paths to `.js`, `.ts` and `.css` files\n\u003e js files has own scope (as modules) with a reference `discovery` that points to an `App` instance from `@discoveryjs/discovery`\n* `serveOnlyAssets` – the same as `assets`, but such assets are included into a model only when the model is serving with `serve` command, or when the model is built with `--serve-only-assets` option (disabled by default)\n* `noscript` – function or path to a module which exports a function to generate content for `\u003cnoscript\u003e` tag; the function can take two arguments: `getData` an async function returns data, and `setup` object\n* `inspector` – option to disable view inspector (default `true`)\n* `router` – option to disable default router (default `true`)\n* `bundles` – additional bundles\n\n```js\nconst path = require('path');\n\nmodule.exports = {\n    ...\n    view: {\n        basedir: __dirname,\n        assets: [\n            './ui/page/default.js',\n            './ui/view/model-custom-view.css',\n            './ui/view/model-custom-view.js',\n            './ui/sidebar.css',\n            './ui/sidebar.js'\n        ],\n        bundles: {\n            'worker.js': './path/to/entry/point.js',\n            'some-styles.css': './path/to/entry/point.css'\n        }\n    }\n};\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscoveryjs%2Fdiscovery-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiscoveryjs%2Fdiscovery-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscoveryjs%2Fdiscovery-cli/lists"}