Merge pull request #385 from christophercr/feature/basehref-docs

docs(stark-build): docs for base url and deploy url customization support

docs/WEBPACK.md

@@ -0,0 +1,65 @@
+# Webpack Customizations
+
+Stark-Build uses several Webpack plugins as well as some utils in order to leverage lots of functionality and customizations to your builds (DEV and PROD).
+
+This is the list of utils and plugins used by the stark-build package:
+
+## Utils
+
+#### Support for custom base URL for assets
+
+Due to the possibility of defining a custom base url in your *index.html* thanks to the [BaseHrefWebpackPlugin](https://github.com/dzonatan/base-href-webpack-plugin "BaseHrefWebpackPlugin"), it is also necessary to customize the path of the different assets (images, styles, etc.). 
+
+To do this, Stark uses the same custom logic implemented in the [@angular-devkit/build-angular](https://github.com/angular/devkit/blob/fe122511feada8d8c554799171e8e43bac950416/packages/angular_devkit/build_angular/src/angular-cli-files/models/webpack-configs/styles.ts "@angular-devkit/build-angular")  to append the custom base url and the deploy url so you don't need to worry about the final path for every resource.
+
+The only thing you need to do is to configure the **baseHref** and **deployUrl** options (if needed) in the *angular.json* file as follows:
+
+```json
+{
+  ...
+  "projects": {
+    "yourProjectName": {
+      ...
+      "architect": {
+        "yourTargetName": {
+          ...
+          "options": {
+            ...
+            "baseHref": "/some-url",  // default value: "/"
+            "deployUrl": "/some-url" // default value: ""
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Plugins
+
+#### [BaseHrefWebpackPlugin](https://github.com/dzonatan/base-href-webpack-plugin "BaseHrefWebpackPlugin")
+Allows to customize the base url in the *index.html* via the webpack config.
+
+In Stark-Build, the custom base url provided to this plugin is the one you define in the **baseHref** option of your project's *angular.json* file:
+
+```json
+{
+  ...
+  "projects": {
+    "yourProjectName": {
+      ...
+      "architect": {
+        "yourTargetName": {
+          ...
+          "options": {
+            ...
+            "baseHref": "/some-url"  // default value: "/"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+This plugin will automatically add the base tag `<base href="<custom-base-url>">` to the *index.html* so you don't need to add it manually yourself.

packages/stark-build/config/webpack.common-data.js

@@ -17,7 +17,8 @@ const starkAppConfig = require(helpers.root("src/stark-app-config.json"));
 // Angular CLI config
 const deployUrl = buildUtils.ANGULAR_APP_CONFIG.deployUrl;
 const baseHref = buildUtils.ANGULAR_APP_CONFIG.baseHref;
-// Maximum resource size to inline (KiB) (as defined in node_modules/@angular/cli/models/webpack-configs/styles.js)
+// Maximum resource size to inline (KiB)
+// (as defined in node_modules/@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/styles.js)
 const maximumInlineSize = 10;
 
 // PostCSS Plugins
@@ -71,7 +72,7 @@ const postcssPlugins = loader => [
 	// plugin to rebase, inline or copy on url().
 	// https://github.com/postcss/postcss-url
 	require("postcss-url")(
-		// configuration taken as is from node_modules/@angular/cli/models/webpack-configs/styles.js
+		// configuration taken as is from node_modules/@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/styles.js
 		{
 			filter: ({ url }) => url.startsWith("~"),
 			url: ({ url }) => {
@@ -81,7 +82,7 @@ const postcssPlugins = loader => [
 		}
 	),
 	require("postcss-url")(
-		// configuration taken as is from node_modules/@angular/cli/models/webpack-configs/styles.js
+		// configuration taken as is from node_modules/@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/styles.js
 		[
 			{
 				// Only convert root relative URLs, which CSS-Loader won't process into require().
@@ -131,11 +132,11 @@ const postcssPlugins = loader => [
 		browsers: ["last 3 versions", "Chrome >= 56"]
 	}),
 
-	// configuration taken as is from node_modules/@angular/cli/models/webpack-configs/styles.js
-	// the hashing format is just [hash] instead of the ones defined in node_modules/@angular/cli/models/webpack-config.js:
+	// configuration taken as is from node_modules/@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/styles.js
+	// the hashing format is just [hash] always instead of the 'outputHashing' value in the angular.json:
 	//
-	// import { getOutputHashFormat } from '@angular/cli/models/webpack-configs/utils';
-	// const hashFormat = getOutputHashFormat("all");  // "media" => development, "all" production
+	// const utils = require("@angular-devkit/build-angular/src/angular-cli-files/models/webpack-configs/utils");
+	// const hashFormat = utils.getOutputHashFormat("all");  // "media" => development, "all" production
 	PostcssCliResources({
 		deployUrl: loader.loaders[loader.loaderIndex].options.ident === "extracted" ? "" : deployUrl,
 		loader,