feat: add "sideEffects": false flag to dist-ready package.json (#776)

Author: dherges

integration/samples/apf/specs/package.ts

@@ -56,6 +56,10 @@ describe(`@sample/apf`, () => {
     it(`should reference "metadata" file`, () => {
       expect(PACKAGE['metadata']).to.equal('sample-apf.metadata.json');
     });
+
+    it(`should apply the 'sideEffects: false' flag by default`, () => {
+      expect(PACKAGE['sideEffects']).to.be.false;
+    });
   });
 
   describe(`secondary/package.json`, () => {
@@ -111,5 +115,9 @@ describe(`@sample/apf`, () => {
     it(`should reference "metadata" file`, () => {
       expect(PACKAGE['metadata']).to.equal('sample-apf-secondary.metadata.json');
     });
+
+    it(`should apply the 'sideEffects: false' flag by default`, () => {
+      expect(PACKAGE['sideEffects']).to.be.false;
+    });
   });
 });

integration/samples/core/package.json

@@ -4,6 +4,7 @@
   "version": "1.0.0-pre.0",
   "private": true,
   "repository": "https://github.com/dherges/ng-packagr.git",
+  "sideEffects": true,
   "peerDependencies": {
     "@angular/common": "^4.1.3",
     "@angular/core": "^4.1.3",

integration/samples/core/specs/package.ts

@@ -34,5 +34,9 @@ describe(`@sample/core`, () => {
     it(`should have 'scripts' section removed`, () => {
       expect(PACKAGE['scripts']).to.be.undefined;
     });
+
+    it(`should keep the 'sideEffects: true' flag`, () => {
+      expect(PACKAGE['sideEffects']).to.be.true;
+    });
   });
 });

src/lib/ng-package-format/entry-point.ts

@@ -34,10 +34,15 @@ import { DirectoryPath, SourceFilePath, CssUrl, DestinationFiles } from './share
  */
 export class NgEntryPoint {
   constructor(
+    /** Values from the `package.json` file of this entry point. */
     public readonly packageJson: any,
+    /** Values from either the `ngPackage` option (from `package.json`) or values from `ng-package.json`. */
     public readonly ngPackageJson: NgPackageConfig,
+    /** Corresponding JSON schema class instantiated from `ngPackageJson` values. */
     private readonly $schema: SchemaClass<NgPackageConfig>,
+    /** Absolute directory path of this entry point's `package.json` location. */
     public readonly basePath: string,
+    /** XX: additional auto-configured data passed for scondary entry point's. Needs better docs. */
     private readonly secondaryData?: { [key: string]: any }
   ) {}
 
@@ -154,4 +159,15 @@ export class NgEntryPoint {
       return this.moduleId.split('/').join(separator);
     }
   }
+
+  /**
+   * Enables the `"sideEffects": false` flag in `package.json`.
+   * The flag is enabled and set to `false` by default which results in more aggressive optimizations applied by webpack v4 builds consuming the library.
+   * To override the default behaviour, you need to set `"sideEffects": true` explicitly in your `package.json`.
+   *
+   * @link https://github.com/webpack/webpack/tree/master/examples/side-effects
+   */
+  public get hasSideEffects(): boolean {
+    return this.packageJson['sideEffects'] === true;
+  }
 }

src/lib/ng-v5/entry-point/write-package.transform.ts

@@ -34,7 +34,9 @@ export const writePackageTransform: Transform = transformFromPromise(async graph
     fesm2015: relativeUnixFromDestPath(destinationFiles.fesm2015),
     typings: relativeUnixFromDestPath(destinationFiles.declarations),
     // XX 'metadata' property in 'package.json' is non-standard. Keep it anyway?
-    metadata: relativeUnixFromDestPath(destinationFiles.metadata)
+    metadata: relativeUnixFromDestPath(destinationFiles.metadata),
+    // webpack v4+ specific flag to enable advanced optimizations and code splitting
+    sideEffects: ngEntryPoint.hasSideEffects
   });
 
   log.success(`Built ${ngEntryPoint.moduleId}`);
@@ -55,18 +57,18 @@ export const writePackageTransform: Transform = transformFromPromise(async graph
  * flattened JavaScript bundles, type definitions, (...).
  *
  * @param entryPoint An entry point of an Angular package / library
- * @param binaries Binary artefacts (bundle files) to merge into `package.json`
+ * @param additionalProperties Additional properties, e.g. binary artefacts (bundle files), to merge into `package.json`
  */
 export async function writePackageJson(
   entryPoint: NgEntryPoint,
   pkg: NgPackage,
-  binaries: { [key: string]: string }
+  additionalProperties: { [key: string]: string | boolean }
 ): Promise<void> {
   log.debug('Writing package.json');
   const packageJson: any = entryPoint.packageJson;
   // set additional properties
-  for (const fieldName in binaries) {
-    packageJson[fieldName] = binaries[fieldName];
+  for (const fieldName in additionalProperties) {
+    packageJson[fieldName] = additionalProperties[fieldName];
   }
 
   // read tslib version from `@angular/compiler` so that our tslib