Merge pull request #1593 from NativeScript/niliev/hmr

[DO NOT MERGE] New nsconfig option for enabling HMR by default

Author: NickIliev

docs/core-concepts/project-structure.md

@@ -90,7 +90,7 @@ This is a secondary `package.json` file in which you can specify the entry point
 {% endangular %}
 
 
-#### Discarding JavaScript exceptions when called from native
+#### Discarding JavaScript Exceptions Called from Native
 
 Normally, an unhandled exception from JavaScript code called from a native API will crash the application showing the stack trace. If you want to prevent such crashes you can override this behavior using the `discardUncaughtJsExceptions` flag.
 
@@ -112,11 +112,11 @@ application.on(application.discardedErrorEvent, function (args) {
 });
 ```
 
-#### Android runtime configuration
+#### Android Runtime Configuration
 
 For desciption of the flags which are specific to the Android runtime see the [Android custom flags article]({% slug android-custom-flags %}).
 
-#### iOS runtime configuration
+#### iOS Runtime Configuration
 
 For description of the flags which are specific to the iOS runtime see the [iOS custom flags article]({% slug ios-custom-flags %}).
 
@@ -126,13 +126,13 @@ The `App_Resources` folder contains the platform-specific resources of the appli
 
 Additionally, you can modify the `App_Resources/iOS/build.xcconfig` or `App_Resources/Android/app.gradle` to add or remove additional build properties for the iOS and Android platforms, respectively.
 
-## The **platforms** directory
+## The **platforms** Directory
 
 The `platforms` directory is created when you start a build or add a target platform to your project. The NativeScript tooling creates a new subdirectory with the respective platform name. These subdirectories have the platform-specific project structure required for native development with the native SDKs of the platform. When the project is prepared for build, the NativeScript tooling copies relevant content from the {% nativescript %}`app`{% endnativescript %}{% angular %}`src`{% endangular%} directory to the platform-specific subdirectory for each target platform.
 
 > **IMPORTANT:** Avoid editing files located in the `platforms` subdirectories because the NativeScript CLI overrides them with the content of the {% nativescript %}`app`{% endnativescript %}{% angular %}`src`{% endangular%} directory during the `prepare <Platform>` process.
 
-## The **package.json** file
+## The **package.json** File
 
 The main `package.json`, which is located in the root directory of the project, contains details about the application, its dependencies and other helpful information. You can set [common npm package.json properties](https://docs.npmjs.com/files/package.json) like `author`, `description` and `version`, or specify the npm packages and [NativeScript plugins]({% slug plugins-infrastructure %}) on which your app depends by modifying the `dependencies` and `devDependencies` attributes.
 
@@ -170,29 +170,30 @@ Here is an example of a basic main `package.json` file:
 }
 ```
 
-## The **hooks** directory
+## The **hooks** Directory
 
 The `hooks` folder exists only when the project depends on plugins that require a hook to function properly. Hooks are executable pieces of code or Node.js scripts that are used to alter or augment the behavior of an extendable NativeScript CLI command. For more information about hooks and how to use them in NativeScript, see [Extending the CLI](https://github.com/NativeScript/nativescript-cli/blob/master/extending-cli.md).
 
 Some of the more common plugins that have hooks are `nativescript-dev-webpack`, `nativescript-dev-typescript` and `nativescript-dev-sass`.
 
-## The **tsconfig.json** file
+## The **tsconfig.json** File
 
 The `tsconfig.json` file is present only in projects that use TypeScript. The file works as a guide during the [transpilation]({% slug transpilers %}) of TypeScript to JavaScript. You can fine-tune the transpilation process by configuring the various [compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html). For more information about `tsconfig.json`, see the official [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
-## The **nsconfig.json** file
+## The **nsconfig.json** File
 
-The `nsconfig.json` is an optional configuration file, located at the root project directory on the same level as the main `package.json` file. This file makes it possible for users to modify the structure of their application. The available configurations are `appPath` and `appResourcesPath`.
+The `nsconfig.json` is an optional configuration file, located at the root project directory on the same level as the main `package.json` file. This file makes it possible for users to modify the structure of their application and to enable/disable the HMR developer experience. The available configurations are `appPath`, `appResourcesPath`, and `useLegacyWorkflow`.
 
-Both paths must be relative to the project root (where the `package.json` file and `platforms` directory are located) in order everything to work as expected. If `appPath` is omitted, the CLI will assume the application files are located inside a folder called {% nativescript %}`app`{% endnativescript %}{% angular %}`src`{% endangular%} inside the project folder. If `appResourcesPath` is omitted, the CLI will assume that they are at their default location - a folder called `App_Resources` inside the folder containing the rest of the app files.
+The paths (`appPath` and `appResourcesPath`) must be relative to the project root (where the `package.json` file and `platforms` directory are located) in order everything to work as expected. If `appPath` is omitted, the CLI will assume the application files are located inside a folder called {% nativescript %}`app`{% endnativescript %}{% angular %}`src`{% endangular%} inside the project folder. If `appResourcesPath` is omitted, the CLI will assume that they are at their default location - a folder called `App_Resources` inside the folder containing the rest of the app files.
 
 > **Important:** To use an `nsconfig.json` file in your project, you must ensure that it meets the following requirements:
 * NativeScript CLI >= 4.0.0
+* The `useLegacyWorkflow` option requires NativeScript CLI >= 5.3.0
 * Android Runtime >= 4.0.0
 * nativescript-dev-sass >= 1.3.6 (if used in the application)
 * nativescript-dev-webpack >= 0.10.1 (if used in the application)
 
-### **nsconfig.json** examples
+### **nsconfig.json** Path examples
 
 Let's assume the project is located at `/d/work/myApplication`.
 
@@ -219,3 +220,12 @@ Let's assume the project is located at `/d/work/myApplication`.
         "appResourcesPath": "resources"
     }
     ```
+
+### **nsconfig.json** enabling HMR example
+
+Enable the HMR developer experience by default. By setting `useLegacyWorkflow` to `false`, you will enable the HMR by default (no need to pass additional flags to have HMR). When omitted, the default value is` true` (default livesync experience without the enhanced HMR).
+    ```JSON
+    {
+        "useLegacyWorkflow": false
+    }
+    ```

docs/performance-optimizations/bundling-with-webpack.md

@@ -137,6 +137,10 @@ Comparison chart for the HMR capabilities versus no-HMR versus no Webpack (pure
 
 > Note: version 5.2 applies changes in application styles at runtime on the current page, thereby it avoids page reloading/navigation and preserves the application state and navigation history.
 
+### Enabling HMR by Default
+
+With NativeScript 5.3 and above the HMR (Hot Module Replacement) can be enabled by default (no need to pass `--hmr` flag). Achieve the above via the `nsconfig.json` file and the `useLegacyWorkflow` property set to `false.` Refer to the [CLI basics article](/start/cli-basics#using-run-with-hmr-by-default) for detailed instruction on this feature.
+
 ### Publishing Application
 
 A bundled version of the application for Android can be built in release with this script:

docs/start/cli-basics.md

@@ -61,6 +61,7 @@ Once your NativeScript mobile project is created, you can start the application
 
 - Using a local build via the `run` command. This option allows you to experience the full developer experience (building and deploying on local emulators and devices). See the [full setup section](#full-setup-using-run) for details.
 
+
 ### Quick Setup Using PREVIEW
 
 > **NOTE**: To complete this section you must finish the NativeScript [CLI quick setup]({% slug quick-start %}).
@@ -238,6 +239,60 @@ The `run` command will again take a few seconds, as the NativeScript CLI will be
 
 Now that you have a full setup in place for developing your apps let’s look at a few additional things you can do.
 
+### Using RUN with HMR
+
+The developer experience significantly improves by using the [HMR (Hot Module Replacement)](/performance-optimizations/bundling-with-webpack#hot-module-replacement) feature introduced in NativeScript 5. The option requires **nativescript-dev-webpack** plugin (enabled by default in all NativeScript 5.x.x templates) and behind the scene creates Webpack bundle with the enhancement of Hot Module Replacement developer experience.
+
+To enable HMR during your development pass the `--hmr` flag (you can emit the `--bundle` which is automatically triggered).
+
+For example:
+```Shell
+tns run --hmr
+```
+
+### Using RUN with HMR by default
+
+With NativeScript 5.3 and above, the CLI provides the option to enable the HMR developer experience by default. This can be achieved by creating a `nsconfig.json` (see the detailed article about [nsconfig file and options](/core-concepts/project-structure#nsconfigjson-examples)) and passing the `useLegacyWorkflow` boolean property.
+
+For example:
+
+_nsconfig.json_
+```JSON
+{
+    "useLegacyWorkflow": false
+}
+```
+
+Then execute the RUN command, and the HMR is enabled.
+```Shell
+tns run
+```
+
+- `useLegacyWorkflow` is set to `false`: The option disables the default livesync, in favor of the enhanced HMR (no need to pass additional flag).
+- `useLegacyWorkflow` is set to `true`(default value): The option enables the default livesync experience (explicit enabling of HMR via `--hmr` flag is still possible).
+
+
+> **Note:** There are conceptual differences when the `useLegacyWorkflow` is used in **debug** build versus when used in **release** builds. When the flag is enabled against a debug build, the extended HMR experience is enabled. However, in cases where the `--release` flag is passed (release build) then only the `--bundle` is executed in the background (No HMR). The reason for this is to avoid bringing additional HMR logic and files into production. For details about the differences between Webpack livesync and HMR refer to [the comparative table](/performance-optimizations/bundling-with-webpack#hot-module-replacement).
+
+#### Enhancement flags for useLegacyWorkflow
+
+The flags `--no-hmr` and `--no-bundle` can be used once the `useLegacyWorkflow` option is set to `false`.
+
+In case, when you have enabled the default HMR via the `useLegacyWorkflow` option, but you need to test without using HMR you can pass the `--no-hmr` flag to disable the feature for the current build. 
+
+For example:
+```Shell
+tns run --no-hmr
+```
+Using `--no-hmr` will effectively provide the default livesync experience with Webpack bundle.
+
+In case, when you have enabled the default HMR via the `useLegacyWorkflow` option, but you want to disable both HMR and Webpack bundling, you can pass `--no-bundle` flag.
+
+For example:
+```Shell
+tns run --no-bundle
+```
+
 ### Next steps
 
 Now that you have a preview workflow set up check out our **Build a Full App** tutorials in NativeScript Playground. If you prefer working in a CLI environment, you can download your tutorial project from Playground and complete the tutorial locally using the `tns preview` command.