The official CLI command for building Dojo 2 applications.
To use @dojo/cli-build-app in a single project, install the package:
npm install @dojo/cli-build-app@dojo/cli-build-app is a command for the @dojo/cli.
There are three modes available to build a Dojo 2 application, dist, dev and test. The mode required can be passed using the --mode flag:
dojo build app --mode distThe built application files are written to the output/{mode selected} directory
Note: dist is the default mode and so can be run without any arguments, dojo build app.
The dist mode creates a production-ready build.
The dev mode creates an application build that has been optimized for debugging and development.
The test mode creates bundles that can be used to run the unit and functional tests of the application.
A web server can be started with the --serve flag while running in dev or dist modes. By default, the application is served on port 9999, but this can be changed with the --port (-p) flag:
# build once and then serve the app on port 3000
dojo build -s -p 3000Building 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).
# start a file-based watch
dojo build -w
# build to an in-memory file system with HMR
dojo build -s -w=memory -m=devEjecting @dojo/cli-build-app will produce the following files under the config/build-app directory:
build-options.json: the build-specific config options removed from the.dojorcejected.config.js: the root webpack config that passes the build options to the appropriate mode-specific config based on the--env.modeflag's value.base.config.js: a common configuration used by the mode-specific configs.dev.config.js: the configuration used during development.dist.config.js: the production configuration.test.config.js: the configuration used when running tests.
As already noted, the dojorc's build-app options are moved to config/build-app/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:
node_modules/.bin/webpack --config=config/build-app/ejected.config.js --env.mode={dev|dist|test}Applications use a .dojorc file at the project root to control various aspects of development such as testing and building. This file, if provided, MUST be valid JSON, and the following options can be used beneath the "build-app" key:
Useful for breaking an application 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.
Widget modules defined used with w() will be automatically converted to a lazily imported, local registry item in the parent widget. This provides a mechanism for declarative code splitting in your application.
{
"build-app": {
"bundles": {
"foo": [
"src/Foo",
"src/Bar"
]
}
}
}
An array of paths to CLDR JSON files. Used in conjunction with the locale and supportedLocales options (see below). If a path contains the string {locale}, that file will be loaded for each locale listed in the locale and supportedLocales properties. For example, with the following configuration the numbers.json file will be loaded for the "en", "es", and "fr" locales:
{
"build-app": {
"locale": "en",
"supportedLocales": [ "es", "fr" ]
"cldrPaths": [
"cldr-data/main/{locale}/numbers.json"
]
}
}
A map of 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 documentation for more information.
The default locale for the application. When the application loads, the root locale is set to the user's locale if it supported (see below), or to the default locale as a fallback.
A parent map that houses settings specific to creating progressive web applications.
Specifies information for a web app manifest. For example:
{
"build-app": {
"pwa": {
"manifest": {
"name": "Todo MVC",
"description": "A simple to-do application created with Dojo 2"
}
}
}
}
Renders the application to HTML during the build and in-lines the critical CSS. This allows the application to effectively render static HTML pages and provide some advantages of SSR (server side rendering) such as performance, SEO etc without the complexities of running a server to support full SSR.
- root (required) : The
idof the root DOM node that applicationmergeonto. - paths (optional): An array of hash routes to render the application for during the build, for more complex routes an object can be provided with a basic "matcher" (regular expression) that is used to match against the applications route on page load. Only supports hash routing.
{
"build-app": {
"build-time-render": {
"root": "app",
"paths": [
"#home",
{
"path": "#comments/9999",
"match": [ "#comments\/.*" ]
}
]
}
}
}Build time rendering exposes a has flag build-time-render that can be used to skip functionality that cannot be executed at build time, for example fetching external data.
if (!has('build-time-render')) {
fetch( /* ... */ );
}Note: The application needs to use the merge API from Projector
An array of supported locales beyond the default. When the application loads, the user's locale is checked against the list of supported locales. If the user's locale is compatible with the supported locales, then the user's locale is used throughout the application. Otherwise, the default locale is used. For example, with the following configuration, the application locale will be set to Pashto or Arabic if either is listed as the user's locale, with Farsi used as the default.
Example:
{
"build-app": {
"locale": "fa",
"supportedLocales": [ "ps", "ar" ],
"compression": "gzip",
"bundles": {
"widgets": [
"src/widgets/Header",
"src/widgets/Footer"
]
}
}
}
We appreciate your interest! Please see the Dojo 2 Meta Repository for the Contributing Guidelines. This repository uses prettier for code style and is configured with a pre-commit hook to automatically fix formatting issues on staged .ts files before performing the commit.
To start working with this package, clone the repository and run npm install.
In order to build the project run grunt dev or grunt dist.
Builds a new test artifact from the repository source code and re-installs the test-app dependencies before running all unit and functional tests.
Builds and packages cli-build-app as dojo-cli-build-app.tgz in the dist directory.
Re-generates the test fixtures in test-app. Assumes that the dependencies have been installed for the test app.
Runs prettier on all .ts files in the src and tests directories, this will fix any detected code style violations.
Test cases MUST be written using Intern using the BDD test interface and Assert assertion interface.
90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.
The 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:
npm test
Once 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.
© 2018 JS Foundation. New BSD license.