Merge pull request #1836 from NativeScript/tachev/webpack-snasphot-aab

fix: remove outdated docs for Webpack and Snasphot, document aab and compileSnapshot

Author: tsonevn

docs/core-concepts/accessing-native-apis-with-javascript.md

@@ -231,8 +231,6 @@ Steps to install and enable
 
  > **Note:** Always install the plugin as a `devDependency` (`npm i tns-platform-declarations --save-dev` flag) to avoid bringing the enormously big declaration files in the output built file.
 
-- As of version 3.0.0 of NativeScript the newly created projects are shipped without `reference.d.ts` file.
-
 Create `reference.d.ts` in the root project directory and add the following:
 ```
 /// <reference path="node_modules/tns-platform-declarations/android.d.ts" />

docs/core-concepts/android-runtime/advanced-topics/debug-android-runtime.md

@@ -39,8 +39,6 @@ NativeScript with plain JavaScript:
 
 `tns prepare android`
 
-> After you have prepared the project, make sure the `tns-android` version is at least 3.4.0, because that's the version the Android Studio support is introduced. You can check the version by running `tns info` inside the project folder.
-
 ### 3. Open the Android Studio project:
 
 * Open Android Studio

docs/core-concepts/android-runtime/debug/debug-tooling.md

@@ -10,8 +10,6 @@ previous_url: /debug-eclipse
 
 The ![previous article](./debug-native.md) shows how to debug the runtime and the application, but what if the problem is at build time?
 
-Since {N} version 4.0 you can easily debug the tools used for building a {N} application.
-
 # Debugging the metadata generator
 
 * Open the android-runtime `test-app` in Android Studio. `/your/path/android-runtime/test-app`

docs/core-concepts/project-structure-app.md

@@ -149,22 +149,21 @@ Here is an example of a basic main `package.json` file:
     "nativescript": {
         "id": "org.nativescript.myApplication",
         "tns-android": {
-            "version": "5.0.0"
+            "version": "6.1.2"
         },
         "tns-ios": {
-            "version": "5.0.0"
+            "version": "6.1.0"
         }
     },
     "description": "My NativeScript Application",
     "license": "MIT",
     "repository": "https://github.com/myApplication",
     "dependencies": {
-        "nativescript-theme-core": "~1.0.4",
-        "tns-core-modules": "~5.0.0"
+        "nativescript-theme-core": "~1.0.6",
+        "tns-core-modules": "~6.1.0"
     },
     "devDependencies": {
-        "nativescript-dev-typescript": "~0.7.0",
-        "typescript": "~2.7.2"
+        "nativescript-dev-webpack": "~1.2.0"
     },
     "readme": "My NativeScript Application"
 }
@@ -174,25 +173,16 @@ Here is an example of a basic main `package.json` file:
 
 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 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` 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`.
+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` and `appResourcesPath`.
 
 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** Path examples
 
 Let's assume the project is located at `/d/work/myApplication`.
@@ -220,12 +210,3 @@ 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/guides/integration-with-existing-ios-and-android-apps/extend-existing-android-app.md

@@ -32,7 +32,7 @@ This article will walk you through setting up an already existing Android Studio
 
 2. You can either use the NativeScriptActivity which is part of the NativeScript framework or you can do the following if you want to override or add new functionality to the NativeScriptActivity:  
     1. Copy the corresponding MyNativeScriptActivity file (.ts or .js depending on your NativeScript application type) from [the following location](https://github.com/NativeScript/sample-extend-android-app/tree/master/common) to your NativeScript application **app** folder. Change the Android Activity referenced in JavaProxy to match that of your actual project.
-    2. If you are using webpack build add the MyNativeScriptActivity file to the **appComponents** array in your **webpack.config.js** file:
+    2. Add the MyNativeScriptActivity file to the **appComponents** array in your **webpack.config.js** file:
 
         ```javascript
             const appComponents = [

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

@@ -16,7 +16,7 @@ Why bundle scripts in a mobile app though? Aren't all files stored on the local
 * Smaller code size. Bundlers traverse the module import graph and do not bundle unused modules. Not using that obscure feature in module X? Don't make your users pay for it then.
 * Tree-shaking. With the advent of ECMAScript 2015 modules, we have new tools that allow stripping unused parts of big modules and further reduce our application size.
 
-NativeScript 6 and above is enabling Webpack by default.
+With NativeScript 6 and above, Webpack is the primary developer workflow and can't be disabled.
 
 ## Introducing Webpack
 
@@ -140,26 +140,33 @@ $ tns build android --env.snapshot --release --keyStorePath ~/path/to/keystore -
 
 Known limitations:
 * No iOS support. Heap snapshot is a V8 feature which is the engine used in the Android Runtime. Providing `--env.snapshot` flag on the iOS bundling commands will not affect.
-* No Windows support. Providing `--env.snapshot` flag on the Android bundling command will not affect Windows machines.
-* Only one Webpack bundle can be snapshotted. By default, this is the `vendor.js` chunk. It contains all external packages used by the application.
+
+
+<h3 id="snapshot-per-architecture">V8 Heap Snapshot per architecture</h3>
+
+The Android app size can be reduced by splitting the app per device architecture. However, the `blob` files generated by the `--env.snapshot` are just assets which cannot be split.
+
+In order to get a maximum app size reduction, you can to pass an additional `--env.compileSnapshot` flag which compiles the static assets produced by `--env.snapshot` into `.so` files allowing the native build to split them per architecture. The snapshot compilation requires the Android NDK installed on your system. It is strongly recommended that the same version of the NDK is used to produce the snapshot file as the one used to compile the {N} runtime itself. The current NDK version used in the runtime can be found in [it's settings.json file](https://github.com/NativeScript/android-runtime/blob/master/build-artifacts/project-template-gradle/settings.json#L3).
+
+> **NOTE**: Read more about reducing the Android app size in the [Android App Bundle article]({% slug android-app-bundle %})
 
 #### NativeScriptSnapshotPlugin configuration
 
 The `NativeScriptSnapshotPlugin` by default comes with the following configuration:
 
 ```JavaScript
 if (snapshot) {
-    plugins.push(new nsWebpack.NativeScriptSnapshotPlugin({
-        chunk: "vendor",
+    config.plugins.push(new nsWebpack.NativeScriptSnapshotPlugin({
+        chunk: "vendor",
         requireModules: [
             "tns-core-modules/bundle-entry-points",
-            // ...
         ],
-        useLibs: true, // set to true to produce *.so and to false (default) to produce *.blob
-        targetArchs: ["arm64", "arm"]
-        projectRoot,
-        webpackConfig: config,
-    }));
+        projectRoot,
+        webpackConfig: config,
+        snapshotInDocker,
+        skipSnapshotTools,
+        useLibs
+    }));
 }
 ```
 
@@ -168,15 +175,16 @@ if (snapshot) {
 * `projectRoot` - path to the app root folder.
 * `webpackConfig` - Webpack configurations object. The snapshot generation modifies the Webpack config object to ensure that the specified bundle will be snapshotted successfully.
 
-#### Other options:
-* `targetArchs` - Since the serialization format of the V8 heap is architecture-specific, we need a different blob file for each V8 library target architecture. The Android Runtime library contains 3 architecture slices - `ia32` (for emulators), `arm` and `arm64` (for devices). However, [if not explicitly specified](https://github.com/NativeScript/android-runtime/issues/614), the `arm` slice is used even on `arm64` devices. In other words, generating a heap snapshot for all supported architectures (`arm`, `arm64`, `ia32`) will guarantee that the snapshotted heap is available on every device/emulator. However, when building for the release, you can leave only `arm`and `arm64` in the `targetArchs` array, which decreases the size of the produced APK file.
-* `v8Version` - Specify the v8 engine version that should be used. By default, the value is determined based on the Android runtime version that the project is using.
+<h4 id="other-options-target-archs">Other options</h4>
+* `targetArchs` - Since the serialization format of the V8 heap is architecture-specific, we need a different blob file for each V8 library target architecture. The Android Runtime library contains 4 architecture slices - `ia32` (`x86`), `ia64` (`x86_64`), `arm` (`armeabi-v7a`) and `arm64` (`arm64-v8a`).
+
+#### Snapshot compilation options:
+* `useLibs` - the option is configurable through `--env.compileSnapshot` and compiles the static assets produced by `--env.snapshot` into `.so` files allowing the native build to split them per architecture. This will reduce the app size when using the `--aab` option.
+* `androidNdkPath` - Path to a local installation of Android NDK. If not set, the plugin is looking for it in ANDROID_NDK_HOME, the global PATH or downloaded from Android Studio.
 
-#### [ABI split](https://docs.nativescript.org/publishing/android-abi-split) options:
-* `useLibs` - Instructs the plugin to produce `.so` instead of `.blob` files.
-* `androidNdkPath` - Path to a local installation of Android NDK.
+> **Note:** The snapshot compilation is the recommended way of reducing the app size along with the [Android App bundle](../tooling/publishing/android-app-bundle.md).
 
-#### Checking if the snapshot is enabled
+#### Advanced debugging - checking if the snapshot is enabled
 If you want to toggle whether specific logic is executed only in the snapshotted context you can use the `global.__snapshot` flag. Its value is `true` only if the current execution happens in the snapshotted context. Once the app is deployed on the device, the value of the flag is changed to `false`. There is also `global.__snapshotEnabled` flag. Its only difference compared to `global.__snapshot` is that its value is `true` in both snapshotted and runtime contexts, given that snapshot generation is enabled.
 
 ```JavaScript
@@ -254,7 +262,7 @@ The TypeScript compiler implements class inheritance, decorators and other featu
 ## Bundling Background Workers
 
 When the application is implementing workers, some additional steps are required to make the project Webpack compatible.
-Check out the [`nativescript-worker-loader`](https://github.com/nativescript/worker-loader) and the [detailed documentation article about using workers](./core-concepts/multithreading-model).
+Check out the [`nativescript-worker-loader`](https://github.com/nativescript/worker-loader) and the [detailed documentation article about using workers](../core-concepts/multithreading-model).
 
 ## Webpack Resources