{"id":43509981,"url":"https://github.com/getndazn/kopytko-packager","last_synced_at":"2026-04-02T13:27:37.866Z","repository":{"id":37866733,"uuid":"380214755","full_name":"getndazn/kopytko-packager","owner":"getndazn","description":"A package builder for the Roku platform.","archived":false,"fork":false,"pushed_at":"2026-03-25T10:05:50.000Z","size":773,"stargazers_count":10,"open_issues_count":9,"forks_count":2,"subscribers_count":58,"default_branch":"master","last_synced_at":"2026-03-26T03:32:45.134Z","etag":null,"topics":["brightscript","build-tool","kopytko","packager","roku"],"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/getndazn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-06-25T11:19:37.000Z","updated_at":"2026-03-25T10:05:34.000Z","dependencies_parsed_at":"2024-06-20T23:28:10.793Z","dependency_job_id":"8106f6b3-54f9-4f34-9d3c-a3ccd8e7cb4d","html_url":"https://github.com/getndazn/kopytko-packager","commit_stats":{"total_commits":69,"total_committers":8,"mean_commits":8.625,"dds":0.5942028985507246,"last_synced_commit":"003671d2a1a62b16d27b3a4c08ef7860ca13d082"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/getndazn/kopytko-packager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getndazn%2Fkopytko-packager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getndazn%2Fkopytko-packager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getndazn%2Fkopytko-packager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getndazn%2Fkopytko-packager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getndazn","download_url":"https://codeload.github.com/getndazn/kopytko-packager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getndazn%2Fkopytko-packager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["brightscript","build-tool","kopytko","packager","roku"],"created_at":"2026-02-03T12:49:30.335Z","updated_at":"2026-04-02T13:27:37.847Z","avatar_url":"https://github.com/getndazn.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kopytko Packager\nA package builder for the Roku platform.\n\nThe packager consists of the following features:\n- generate environment-specific manifest\n- copy files of external modules (\"Kopytko Modules\") installed via NPM\n- import internal and external brightscript dependencies\n- pack \u0026 zip the files\n- deploy a package to the Roku device\n- rekey the Roku device with given signed package\n- generate a package ready to upload to the Roku channel\n- prepare and build an app for the Visual Studio Code [extension](https://github.com/RokuCommunity/vscode-brightscript-language)\n- take a screenshot of the dev app\n\n## Listing\n- [Prerequisites](#prerequisites)\n- [Quick start](#quick-start)\n- [Configuration](#configuration)\n- [Scripts](#scripts)\n- [Plugins](#plugins)\n  - [Generating manifest file](#generating-manifest-file)\n  - [Copying external Kopytko Modules](#copying-external-kopytko-modules)\n  - [Dependencies importing mechanism](#dependencies-importing-mechanism)\n- [Creating Kopytko Module](#creating-kopytko-module)\n\n## Prerequisites\n- node version 16+\n- npm version 8+\n\n## Quick start\n1. Install the Packager\n```\nnpm install @dazn/kopytko-packager --save-dev\n```\n2. Create `.kopytkorc` in the root folder with minimal configuration\n```json\n{\n  \"baseManifest\": \"manifest/base.js\"\n}\n```\n- If your app code is not located under default `/app`, configure it in a `sourceDir` attribute\n- Path to base manifest is only example\n\n3. Create a base manifest file\n```js\nconst { baseManifest } = require('@dazn/kopytko-packager');\n\nmodule.exports = {\n  ...baseManifest,\n  title: 'Your app title',\n  mm_icon_focus_hd: 'pkg:/images/icon.png', // it is only an example path\n  mm_icon_focus_sd: 'pkg:/images/icon.png',\n  splash_screen_hd: 'pkg:/images/splash.png',\n  splash_screen_sd: 'pkg:/images/splash.png',\n}\n```\n4. Configure start script in your package.json\n```json\n\"scripts\": {\n  \"start\": \"node node_modules/@dazn/kopytko-packager/scripts/start.js\"\n}\n```\n5. Start the app\n```\nnpm start\n```\n## Kopytko cli package\nIt is recommended to use [kopytko-cli](https://github.com/getndazn/kopytko-cli) package and add it to package.json scripts:\n\n```\nnpm install @dazn/kopytko-packager --save-dev\n```\n\n```json\n\"scripts\": {\n  \"start\": \"kopytko start\",\n  \"build\": \"kopytko build\",\n  \"test\": \"kopytko test\"\n}\n```\n\n## Configuration\nThe main configuration file `.kopytkorc` should be placed in the root folder of the project. The example file looks like this:\n```json\n{\n  \"archivePath\": \"/dist/kopytko_archive.zip\",\n  \"generatedPackagePath\": \"/dist/kopytko_package.pkg\",\n  \"signedPackagePath\": \"/previous/signed.pkg\",\n  \"baseManifest\": \"/manifest/base.js\",\n  \"localManifestOverride\": \"/manifest/local.${args.env}.js\",\n  \"screenshotDir\": \"/dist\",\n  \"pluginDefinitions\": {},\n  \"plugins\": [],\n  \"sourceDir\": \"/app\",\n  \"environments\": {\n    \"production\": {\n      \"manifest\": \"/env/production.js\",\n      \"plugins\": []\n    },\n    \"staging\": {\n      \"manifest\": \"/env/staging.js\"\n    },\n    \"test\": {\n      \"manifest\": \"/env/test.js\"\n    }\n  }\n}\n```\nAvailable fields:\n- `archivePath [@type string @optional]` - path to the app archive to generate; default value as in the example file above\n- `generatedPackagePath [@type string @optional]` - path to the app package to generate; default value as in the example file above\n- `baseManifest [@type string @required]` - base manifest file path. Having the file is sufficient to run the Roku app\n- `localManifestOverride [@type string @optional]` - path to the configuration file that overrides all other settings. Usually the file is on the git ignore list\n- `screenshotDir [@type string @optional]` - the directory where screenshots will be saved; default value as in the example file above\n- `pluginDefinitions [@type [name: string]:object @optional]` - plugin definitions (see [plugins](#plugins))\n- `plugins @optional` - global plugins list (see [plugins](#plugins))\n- `environments [@type [name: string]:object @optional]` - list of environments. The name should correspond to the `ENV` value. Each environment entry consists of:\n  - `manifest [@type string @required]` - path to configuration file\n  - `plugins` environment's plugins list (see [plugins](#plugins))\n- `sourceDir [@type string @optional]` - directory of app's source code; default value as in the example file above\n- `tempDir [@type string @optional]` - absolute path of a temporary folder used during a building process as a project directory. After build, it is removed; default value is operating system directory for temporary files\n\narchivePath and generatedPackagePath also could be defined as string templates to dynamically generate name of the created files.\nExample of generatedPackagePath: 'MyApp-v${manifest.major_version}.${manifest.minor_version}.${manifest.build_version}-${args.env}.pkg'.\nResolves into: 'MyApp-v1.0.0-production.pkg'.\nAbove example will take values from given manifest file and arguments passed to the build or generate-package script.\n\nThe configuration files work in waterfall scheme meaning that `baseManifest` is loaded as the first file. Each environment entry overrides base configuration. The `localManifestOverride` is loaded as the last one overriding all others.\n\n## Scripts\nThe packager contains the following scripts:\n- `scripts/build.js` - builds the app\n- `scripts/start.js` - builds and deploys the app to the device\n- `scripts/generate-package.js` - rekey device if needed, builds, deploys the app to the device and finally signs and download the package\n- `scripts/prepare-for-vsc.js` - helpful when using debugging protocol in the VSC [extension](https://github.com/RokuCommunity/vscode-brightscript-language)\n- `scripts/screenshot.js` - takes a screenshot of the current dev application (works only with dev channel), screenshot file name - `Screenshot_\u003cDate as ISOString\u003e.jpg`\n\nExample usage:\n```json\n\"scripts\": {\n  \"build-prod\": \"node node_modules/@dazn/kopytko-packager/scripts/build.js --env=production\",\n  \"start\": \"node node_modules/@dazn/kopytko-packager/scripts/start.js\"\n}\n```\n\nAvailable parameters:\n- `env` - your environment value that matches entry in the [.kopytkorc](#configuration) file. Default value (if not passed) is \"dev\"\n- `rokuDevPassword` - dev password\n- `rokuDevUser` - dev user\n- `rokuDevId` - dev id, needed to rekey the device\n- `rokuDevSigningPassword` - dev signing password needed to rekey the device and sign packages\n- `rokuIP` - IP of your roku device\n- `signedPackagePath` - path to the package of the existing app (signed package), needed to rekey the device\n- `telnet` - true/false, when true the packager will open the telnet session after deploying app to the device\n- `forceHttp` - true/false, when true all the urls in the manifest file that start with https will be overwritten to http\n\nIf an unnamed parameter is passed, it is treated as `env` parameter:\n```\nnpm start -- production\n# is a shortcut for:\nnpm start -- --env=production\n```\n\n### .env file\nTo avoid the necessity of passing parameter with every script run, a .env file could be used.\nDocumentation can be found [here](https://www.npmjs.com/package/dotenv).\n\nAvailable fields: `ENV`, `ROKU_DEV_ID`, `ROKU_DEV_PASSWORD`, `ROKU_DEV_SIGNING_PASSWORD`, `ROKU_DEV_USER`, `ROKU_IP`, `SIGNED_PACKAGE_PATH`, `TELNET`, `FORCE_HTTP`\n\n### Generate package script\n\nBy running this kopytko-packager will create a signed package.\nThis script automates [Packaging Roku channels](https://developer.roku.com/en-gb/docs/developer-program/publishing/packaging-channels.md)\n\nIt contains 4 steps:\n- [rekey device (if needed)](https://developer.roku.com/en-gb/docs/developer-program/publishing/packaging-channels.md#rekeying)\n- build an app for a given environment\n- deploy an app to the Roku device\n- [sign deployed app and download the generated package from the Roku device](https://developer.roku.com/en-gb/docs/developer-program/publishing/packaging-channels.md#step-4-packaging-the-sideloaded-channel)\n\nPackage will be saved under generatedPackagePath if it was provided in `.kopytkorc` file,\nor in `/dist/kopytko_package.pkg` if generatedPackagePath was not provided.\n\nTo be able to generate the package following script arguments are required (or env variables):\n- ROKU_DEV_ID\n- ROKU_DEV_PASSWORD\n- ROKU_DEV_SIGNING_PASSWORD\n- ROKU_DEV_USER\n- ROKU_IP\n- SIGNED_PACKAGE_PATH\n\nIf you already have an app on your Roku channel, you will need to provide a previously signed package, to rekey the Roku device.\nIf this is your first version of the app and you don't have ROKU_DEV_ID and ROKU_DEV_SIGNING_PASSWORD yet:\n1. [Open a telnet session](https://developer.roku.com/en-gb/docs/developer-program/publishing/packaging-channels.md#step-2-open-a-telnet-session)\n2. [Generate new signing keys](https://developer.roku.com/en-gb/docs/developer-program/publishing/packaging-channels.md#step-3-run-the-genkey-utility-to-create-a-signing-key).\n\n## Plugins\n\nPlugin is a code triggered during the build process of a project. There are few built-in plugins,\none of them is executed regardless .kopytkorc config (kopytko-generate-manifest), but you can use and create\ncustom plugins. To get information how to configure or write your own plugin check [/docs/PLUGINS.md](/docs/PLUGINS.md).\n\nBuilt-in plugins:\n\n### Generating manifest file\nKopytko packager dynamically generates the manifest file by transpiling JavaScript configuration files,\nso you don't have to keep it in the source code anymore. It is done by the kopytko-generate-manifest plugin,\nconfigured out-of-the-box.\n\nThe example default manifest file:\n```javascript\nmodule.exports = {\n  title: 'Some Title',\n  bs_const: {\n    debug: true,\n  },\n};\n```\nwill be transpiled to a `manifest` file:\n```\ntitle=Some Title\nbs_const=debug=true\n```\n\nYou can override `@dazn/kopytko-packager/base-manifest.js` which contains all required by Roku fields and dynamically\nsets app version based on your package.json.\n\n### Copying external Kopytko Modules\n\n`kopytko-copy-external-dependencies` plugin lets you use external Kopytko Modules. A Kopytko Module is an NPM module\nwith the `kopytko-module` keyword.\nThe plugin creates a dependency list based on your package prod dependencies (and their prod dependencies, recursively)\nand direct dev dependencies (**without** their any dependencies). If your project in overall has dependencies\non the same module but in different versions, the plugin will automatically use only the highest version of every\nmajor version dependency.\nOnce a dependency list is generated, the plugin automatically copies their `/components` and `/source` directories\n(taking into account `kopytkoModuleDir` value configured in dependencies package.json file). So far the plugin **doesn't**\ncopies neither images nor fonts directories.\n\nYou can get the list of available public Kopytko Modules [here](https://www.npmjs.com/search?q=keywords%3Akopytko-module).\nIf you want to share your Roku library with the community and create your own Kopytko Module, check\nthe [Creating Kopytko Module](#creating-kopytko-module) paragraph.\n\nThe plugin creates\n\n### Dependencies importing mechanism\n\nImport dependencies from internal files and external Kopytko Modules using the `@import` annotation.\nEach of dependency will be automatically added as a `\u003c/script\u003e` entry into the scope of XML file.\nNested dependencies and copying external Kopytko Modules files to the package supported.\n\n#### Configuration\nAdd predefined, built-in `kopytko-import-dependencies` and, if you use external Kopytko Modules, `kopytko-copy-external-dependencies`\nplugins into your .kopytkorc config file. We recommend configuring `kopytko-copy-external-dependencies` to be run before environment plugins\nso every next plugin can manipulate dependencies code if needed:\n ```json\n \"plugins\": [\n    { \"name\": \"kopytko-copy-external-dependencies\", \"preEnvironmentPlugin\": true },\n    \"kopytko-import-dependencies\"\n  ],\n ```\n\n- `kopytko-copy-external-dependencies` copies all (even unused in the project) files from dependency modules\n- `kopytko-import-depenencies` translates `@import` annotations and imports related dependencies in XML files\n\n#### Importing internal dependencies\nImport other internal .brs file via `' @import /\u003cpath\u003e` at the beginning of the file.\nThe `pkg:` prefix will be automatically added into the XML file.\n\nExample:\n```brightscript\n' @import /components/utils.brs\n' @import /source/superFunction.brs\nfunction init()\nend function\n```\n\n#### Importing external dependencies\nImport a .brs file from an external Kopytko Module via `' @import /\u003cpath\u003e from \u003cpackage-name\u003e`.\nEvery external dependency entry will be automatically added into the XML file with a proper path to the copied file.\n\nAll functions and components definitions and usages will be prefixed with a standardized module name and version\n(normalized to Brightscript's requirements). E.g. `function superFunction()` from `@kopytko/utils` v1  will be renamed into `kopytko_utils_v1_superFunction`.\nThis mechanism prevents naming collisions (e.g. when an imported external module has defined a function with the same name as\none of your internal functions).\n\nExample:\n```brightscript\n' @import /components/externalUtil.brs from @kopytko/utils\n```\nwill be changed into `pkg:/components/kopytko_modules/kopytko_utils_v1/externalUtils.brs` XML script entry.\n\nKopytko-packager imports nested external dependencies out-of-the-box.\n\n## Creating Kopytko Module\n- add `\"kopytko-module\"` to \"keywords\" field in your module's package.json file\n- if your `components` and `source` directories are not placed in the root directory, configure it in the\n`\"kopytkoModuleDir\"` field in package.json, e.g. `\"kopytkoModuleDir\": \"app/\"`\n- be aware so far Kopytko Module supports copying only the two mentioned above directories\n- if your module is designed to be used as a direct dev dependency (e.g. a module for debugging the non-production app),\n  and it uses some other Kopytko Modules, define them as `peerDependency` because Kopytko Packager doesn't install any dependencies\n  of direct dev dependencies. Thanks to this, it will notify the end user to install your peer dependencies as dev dependencies too.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetndazn%2Fkopytko-packager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetndazn%2Fkopytko-packager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetndazn%2Fkopytko-packager/lists"}