{"id":19973789,"url":"https://github.com/dojo/cli-build-widget","last_synced_at":"2025-07-18T07:07:03.857Z","repository":{"id":40790847,"uuid":"117588807","full_name":"dojo/cli-build-widget","owner":"dojo","description":"Command for building Dojo widgets ","archived":false,"fork":false,"pushed_at":"2022-12-09T05:02:28.000Z","size":15329,"stargazers_count":6,"open_issues_count":17,"forks_count":18,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-17T09:45:26.857Z","etag":null,"topics":["build","custom-elements","dojo","widgets"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dojo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-15T19:51:24.000Z","updated_at":"2024-01-04T15:49:31.000Z","dependencies_parsed_at":"2023-01-25T11:15:55.350Z","dependency_job_id":null,"html_url":"https://github.com/dojo/cli-build-widget","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/dojo/cli-build-widget","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dojo%2Fcli-build-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dojo%2Fcli-build-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dojo%2Fcli-build-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dojo%2Fcli-build-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dojo","download_url":"https://codeload.github.com/dojo/cli-build-widget/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dojo%2Fcli-build-widget/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265716306,"owners_count":23816354,"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":["build","custom-elements","dojo","widgets"],"created_at":"2024-11-13T03:12:53.983Z","updated_at":"2025-07-18T07:07:03.829Z","avatar_url":"https://github.com/dojo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @dojo/cli-build-widget\n\n[![Build Status](https://travis-ci.org/dojo/cli-build.svg?branch=master)](https://travis-ci.org/dojo/cli-build-widget)\n[![Build status](https://ci.appveyor.com/api/projects/status/31du0respjt6p98i/branch/master?svg=true)](https://ci.appveyor.com/project/Dojo/cli-build-widget/branch/master)\n[![codecov](https://codecov.io/gh/dojo/cli-build-widget/branch/master/graph/badge.svg)](https://codecov.io/gh/dojo/cli-build-widget)\n[![npm version](https://badge.fury.io/js/%40dojo%2Fcli-build-widget.svg)](https://badge.fury.io/js/%40dojo%2Fcli-build-widget)\n\nThe official CLI command for building Dojo custom elements and widget libraries.\n\n- [Usage](#usage)\n- [Features](#features)\n  - [Project Structure](#project-structure)\n  - [Building](#building)\n  - [Serving](#serving-an-example-page)\n  - [Watching](#watching)\n  - [Eject](#eject)\n  - [Configuration](#configuration)\n- [How do I contribute?](#how-do-i-contribute)\n  - [Installation](#installation)\n  - [Testing](#testing)\n- [Licensing information](#licensing-information)\n\n## Usage\n\nTo use `@dojo/cli-build-widget` in a single project, install the package:\n\n```bash\nnpm install @dojo/cli-build-widget\n```\n\n## Features\n\n`@dojo/cli-build-widget` is an optional command for the [`@dojo/cli`](https://github.com/dojo/cli).\n\nBy default widgets are built using an evergreen configuration, meaning that the build process:\n\n* Prefers `.mjs` modules over `.js` modules\n* Uses `{ target: 'es6', module: 'esnext' }` Typescript compiler options\n* Elides features based on the `chrome` flag from [`dojo/webpack-contrib`](https://github.com/dojo/webpack-contrib#available-features)\n\n### Project Structure\n\nA custom elements or library project is expected to have the following directory and file structure:\n\n```\nsrc/\n\tcustom-element-parent/\n\t\tcustomElementParent.m.css\n\t\tCustomElementParent.ts\n\tcustom-element-child/\n\t\tcustomElementChild.m.css\n\t\tCustomElementChild.ts\ntests/\n\tunit/\n\tfunctional/\n.dojorc\n```\n\n### Building\n\n`@dojo/cli-build-widget` can be used to build either custom elements or a library of Dojo widgets. Library builds can be enabled with the `--target=lib` (or `-t lib`) flag. While custom element builds aim to provide a minimum set of files required to render an individual custom element in the browser, library builds simply 1) transpile TypeScript to `.mjs` and legacy `.js` files, 2) build, minimize, and generate `.d.ts` and `.js` files for CSS modules, 3) and copy font and image assets.\n\nWhen building a Dojo widgets library, any widget that should be included MUST be specified in the `--widgets` option (see both [Widgets](#widgets) and [Configuration](#configuration) below). When present, `src/main.ts` takes precedence.\n\nThere are two modes available to build Dojo custom elements or widget libraries: `dist` and `dev`. When building custom elements, a `test` mode is also provided. The mode required can be passed using the `--mode` flag:\n\n```bash\n# For custom element builds\ndojo build --mode dist\n\n# For library builds\ndojo build --mode dist --target lib\n```\n\nThe built files are written to the `output/{mode selected}` directory. The output mirrors the `src` directory, so if a custom element is located at `src/custom-element/CustomElement.s`, the built element will be output to `output/{mode}/custom-element/CustomElement.js`.\n\nNote: `dist` is the default mode and so can be run without any arguments, `dojo build`.\n\n#### Dist Mode\n\nThe `dist` mode creates a production ready build.\n\n#### Dev mode\n\nThe `dev` mode creates a build that has been optimized for debugging and development.\n\n#### Test mode\n\nThe `test` mode creates bundles that can be used to run the unit and functional tests for the custom element(s).\n\n### Serving An Example Page\n\nA web server can be started with the `--serve` flag. By default, the build is served on port 9999, but this can be changed with the `--port` (`-p`) flag:\n\n```bash\n# build once and then serve on port 3000\ndojo build -s -p 3000\n```\n\n### Watching\n\nBuilding with the `--watch` option observes the file system for changes, and recompiles to the appropriate `output/{dist|dev|test}` directory, depending on the current `--mode`. When used in the conjunction with the `--serve` option and `--mode=dev`, `--watch=memory` can be specified to enable automatic browser updates and hot module replacement (HMR).\n\n```bash\ndojo build -w # start a file-based watch\ndojo build -s -w=memory -m=dev # build to an in-memory file system with HMR\n```\n\n### Widgets\n\nThe path for widgets to build can be provided using the repeating option `--widgets`:\n\n```bash\ndojo build --widgets src/custom-element-child/CustomElementChild --widgets src/custom-element-parent/CustomElementParent\n```\n\n### Legacy\n\nTo build widgets for legacy environments use the `--legacy` or `-l` flag. Widgets built with the legacy flag will need to include the polyfill for the [native shim](https://github.com/webcomponents/custom-elements/blob/master/src/native-shim.js). For library builds, both legacy and evergreen JavaScript files are output side-by-side.\n\n### Eject\n\nEjecting `@dojo/cli-build-widget` will produce the following files under the `config/build-widget` directory:\n\n- `build-options.json`: the build-specific config options removed from the `.dojorc`\n- `ejected.config.js`: the root webpack config that passes the build options to the appropriate mode-specific config based on the `--env.mode` flag's value.\n- `base.config.js`: a common configuration used by the mode-specific configs.\n- `dev.config.js`: the configuration used during development.\n- `dist.config.js`: the production configuration.\n- `test.config.js`: the configuration used when running tests.\n- `template/custom-element.js`: A template that registers custom elements\n\nAs already noted, the dojorc's `build-widget` options are moved to `config/build-widget/build-options.json` after ejecting. Further, the modes are specified using webpack's `env` flag (e.g., `--env.mode=dev`), defaulting to `dist`. You can run a build using webpack with:\n\n```bash\nnode_modules/.bin/webpack --config=config/build-widget/ejected.config.js --env.mode={dev|dist|test}\n```\n\n### Configuration\n\nCustom element/widget library projects use a `.dojorc` file at the project root to control various aspects of development such as testing and building. This file is required to build the project, it MUST be valid JSON, and for widget projects it MUST provide at least a `widgets` array with the widget paths. All other values are options. The following options can be used beneath the `\"build-widget\"` key:\n\n#### `widgets`: string[]\n\nContains paths _relative to the project root_ to the widgets that should be built.\n\n```json\n{\n\t\"build-widget\": {\n\t\t\"widgets\": [\n\t\t\t\"src/menu-item/MenuItem\",\n\t\t\t\"src/menu/Menu\"\n\t\t]\n\t}\n}\n```\n\n#### `bundles`: object\n\nUseful for breaking a build into smaller bundles, the `bundles` option is a map of webpack bundle names to arrays of modules that should be bundled together. For example, with the following configuration both `src/Foo` and `src/Bar` will be grouped in the `foo.[hash].js` bundle:\n\n```\n{\n\t\"build-widget\": {\n\t\t\"bundles\": {\n\t\t\t\"foo\": [\n\t\t\t\t\"src/Foo\",\n\t\t\t\t\"src/Bar\"\n\t\t\t]\n\t\t}\n\t}\n}\n```\n\n#### `features`: object\n\nA map of [`has`](https://github.com/dojo/has/) features to boolean flags that can be used when building in `dist` mode to remove unneeded imports or conditional branches. See the [`static-build-loader`](https://github.com/dojo/webpack-contrib/#static-build-loader) documentation for more information.\n\n## How do I contribute?\n\nWe appreciate your interest! Please see the [Dojo Meta Repository](https://github.com/dojo/meta#readme) for the Contributing Guidelines. This repository uses [prettier](https://prettier.io/) for code style and is configured with a pre-commit hook to automatically fix formatting issues on staged `.ts` files before performing the commit.\n\n### Installation\n\nTo start working with this package, clone the repository and run:\n\n```\nnpm install\n```\n\nIn order to build the project, you can run all the build steps via:\n\n```\nnpm run build\n```\n\n### Scripts\n\n#### watch\n\nWill run a watcher process which looks for changes in the source code TypeScript files and runs the build scripts to update the contents of the built files in dist with latest changes made.\n\n#### clean\n\nRuns the clean up script which removes any built files like output, dist, coverage which get created on build and testing steps.\n\n#### lint\n\nRuns the [ts-lint](https://palantir.github.io/tslint/) and [prettier](https://prettier.io/) on all `.ts` files in the `src` and `tests` directories.  ts-lint will ensure that all linting rules have been abided by and prettier will fix any detected code style violations in the code.\n\n### Testing\n\nTest cases MUST be written using [Intern](https://theintern.github.io) using the BDD test interface and Assert assertion interface.\n\n90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.\n\nThe command is tested by running via the Dojo CLI and asserting the build output against known fixtures. To do this, a test artifact needs to be built and installed into the `test-app`:\n\n```\nnpm test\n```\n\n### Testing\n\nTest cases MUST be written using [Intern](https://theintern.github.io) using the BDD test interface and Assert assertion interface.\n\n90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.\n\nThe command is tested by running via the Dojo CLI and asserting the build output against known fixtures. To do this, a test artifact needs to be built and installed into the `test-app`:\n\n```\nnpm test\n```\n\nOnce the test artifact has been installed, if there have been no changes to the command code `grunt test` can be used to repeat the tests.\n## Licensing information\n\n© 2019 [JS Foundation](https://js.foundation/). [New BSD](http://opensource.org/licenses/BSD-3-Clause) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdojo%2Fcli-build-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdojo%2Fcli-build-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdojo%2Fcli-build-widget/lists"}