feat(@angular-devkit/build-angular): enable inlining of critical CSS optimizations

This is another feature that we mentioned in the Eliminate Render Blocking Requests RFC (#18730)

Inlining of critical CSS is turned off by default. To opt-in this feature set `inlineCritical` to `true`.

Example:
```json
"configurations": {
  "production": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.prod.ts"
      }
    ],
    "optimization": {
      "styles": {
        "minify": true,
        "inlineCritical": true,
       }
    },
```

To learn more about critical CSS see;
https://web.dev/defer-non-critical-css
https://web.dev/extract-critical-css/

In a future version of the Angular CLI `inlineCritical` will be enabled by default.

Closes: #17966
Closes: #11395
Closes: #19445

Author: alan-agius4

package.json

@@ -142,6 +142,7 @@
     "conventional-commits-parser": "^3.0.0",
     "copy-webpack-plugin": "6.3.2",
     "core-js": "3.8.0",
+    "critters": "0.0.6",
     "css-loader": "5.0.1",
     "cssnano": "4.1.10",
     "debug": "^4.1.1",

packages/angular/cli/lib/config/schema.json

@@ -715,7 +715,7 @@
               "additionalProperties": false
             },
             "optimization": {
-              "description": "Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination and fonts inlining. For more information, see https://angular.io/guide/workspace-config#optimization-and-source-map-configuration.",
+              "description": "Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination, inlining of critical CSS and fonts inlining. For more information, see https://angular.io/guide/workspace-config#optimization-and-source-map-configuration.",
               "oneOf": [
                 {
                   "type": "object",
@@ -726,9 +726,29 @@
                       "default": true
                     },
                     "styles": {
-                      "type": "boolean",
                       "description": "Enables optimization of the styles output.",
-                      "default": true
+                      "default": true,
+                      "oneOf": [
+                        {
+                          "type": "object",
+                          "properties": {
+                            "minify": {
+                              "type": "boolean",
+                              "description": "Minify CSS definitions by removing extraneous whitespace and comments, merging identifiers and minimizing values.",
+                              "default": true
+                            },
+                            "inlineCritical": {
+                              "type": "boolean",
+                              "description": "Extract and inline critical CSS definitions to improve first paint time.",
+                              "default": false
+                            }
+                          },
+                          "additionalProperties": false
+                        },
+                        {
+                          "type": "boolean"
+                        }
+                      ]
                     },
                     "fonts": {
                       "description": "Enables optimization for fonts. This requires internet access.",

packages/angular_devkit/build_angular/BUILD.bazel

@@ -145,6 +145,7 @@ ts_library(
         "@npm//circular-dependency-plugin",
         "@npm//copy-webpack-plugin",
         "@npm//core-js",
+        "@npm//critters",
         "@npm//css-loader",
         "@npm//cssnano",
         "@npm//file-loader",

packages/angular_devkit/build_angular/package.json

@@ -28,6 +28,7 @@
     "circular-dependency-plugin": "5.2.2",
     "copy-webpack-plugin": "6.3.2",
     "core-js": "3.8.0",
+    "critters": "0.0.6",
     "css-loader": "5.0.1",
     "cssnano": "4.1.10",
     "file-loader": "6.2.0",

packages/angular_devkit/build_angular/src/app-shell/app-shell_spec.ts

@@ -22,6 +22,9 @@ describe('AppShell Builder', () => {
   afterEach(async () => host.restore().toPromise());
 
   const appShellRouteFiles = {
+    'src/styles.css': `
+      p { color: #000 }
+    `,
     'src/app/app-shell/app-shell.component.html': `
       <p>
         app-shell works!
@@ -262,4 +265,24 @@ describe('AppShell Builder', () => {
     // Close the express server.
     server.close();
   });
+
+  it('critical CSS is inlined', async () => {
+    host.writeMultipleFiles(appShellRouteFiles);
+    const overrides = {
+      route: 'shell',
+      browserTarget: 'app:build:production,inline-critical-css',
+    };
+
+    const run = await architect.scheduleTarget(target, overrides);
+    const output = await run.result;
+    await run.stop();
+
+    expect(output.success).toBe(true);
+    const fileName = 'dist/index.html';
+    const content = virtualFs.fileBufferToString(host.scopedSync().read(normalize(fileName)));
+
+    expect(content).toContain('app-shell works!');
+    expect(content).toContain('p{color:#000;}');
+    expect(content).toMatch(/<link rel="stylesheet" href="styles\.[a-z0-9]+\.css" media="print" onload="this\.media='all'">/);
+  });
 });

packages/angular_devkit/build_angular/src/app-shell/index.ts

@@ -18,6 +18,9 @@ import * as path from 'path';
 import { BrowserBuilderOutput } from '../browser';
 import { Schema as BrowserBuilderSchema } from '../browser/schema';
 import { ServerBuilderOutput } from '../server';
+import { normalizeOptimization } from '../utils';
+import { readFile, writeFile } from '../utils/fs';
+import { InlineCriticalCssProcessor } from '../utils/index-file/inline-critical-css';
 import { augmentAppWithServiceWorker } from '../utils/service-worker';
 import { Spinner } from '../utils/spinner';
 import { Schema as BuildWebpackAppShellSchema } from './schema';
@@ -27,16 +30,18 @@ async function _renderUniversal(
   context: BuilderContext,
   browserResult: BrowserBuilderOutput,
   serverResult: ServerBuilderOutput,
+  spinner: Spinner,
 ): Promise<BrowserBuilderOutput> {
   // Get browser target options.
   const browserTarget = targetFromTargetString(options.browserTarget);
-  const rawBrowserOptions = await context.getTargetOptions(browserTarget);
+  const rawBrowserOptions = (await context.getTargetOptions(browserTarget)) as JsonObject & BrowserBuilderSchema;
   const browserBuilderName = await context.getBuilderNameForTarget(browserTarget);
   const browserOptions = await context.validateOptions<JsonObject & BrowserBuilderSchema>(
     rawBrowserOptions,
     browserBuilderName,
   );
 
+
   // Initialize zone.js
   const root = context.workspaceRoot;
   const zonePackage = require.resolve('zone.js', { paths: [root] });
@@ -54,10 +59,18 @@ async function _renderUniversal(
     normalize((projectMetadata.root as string) || ''),
   );
 
+  const { styles } = normalizeOptimization(browserOptions.optimization);
+  const inlineCriticalCssProcessor = styles.inlineCritical
+    ? new InlineCriticalCssProcessor({
+      minify: styles.minify,
+      deployUrl: browserOptions.deployUrl,
+    })
+    : undefined;
+
   for (const outputPath of browserResult.outputPaths) {
     const localeDirectory = path.relative(browserResult.baseOutputPath, outputPath);
     const browserIndexOutputPath = path.join(outputPath, 'index.html');
-    const indexHtml = fs.readFileSync(browserIndexOutputPath, 'utf8');
+    const indexHtml = await readFile(browserIndexOutputPath, 'utf8');
     const serverBundlePath = await _getServerModuleBundlePath(options, context, serverResult, localeDirectory);
 
     const {
@@ -86,13 +99,25 @@ async function _renderUniversal(
       url: options.route,
     };
 
-    const html = await renderModuleFn(AppServerModuleDef, renderOpts);
+    let html = await renderModuleFn(AppServerModuleDef, renderOpts);
     // Overwrite the client index file.
     const outputIndexPath = options.outputIndexPath
       ? path.join(root, options.outputIndexPath)
       : browserIndexOutputPath;
 
-    fs.writeFileSync(outputIndexPath, html);
+    if (inlineCriticalCssProcessor) {
+      const { content, warnings, errors } = await inlineCriticalCssProcessor.process(html, { outputPath });
+      html = content;
+
+      if (warnings.length || errors.length) {
+        spinner.stop();
+        warnings.forEach(m => context.logger.warn(m));
+        errors.forEach(m => context.logger.error(m));
+        spinner.start();
+      }
+    }
+
+    await writeFile(outputIndexPath, html);
 
     if (browserOptions.serviceWorker) {
       await augmentAppWithServiceWorker(
@@ -145,9 +170,15 @@ async function _appShellBuilder(
 
   // Never run the browser target in watch mode.
   // If service worker is needed, it will be added in _renderUniversal();
+  const browserOptions = (await context.getTargetOptions(browserTarget)) as JsonObject & BrowserBuilderSchema;
+
+  const optimization = normalizeOptimization(browserOptions.optimization);
+  optimization.styles.inlineCritical = false;
+
   const browserTargetRun = await context.scheduleTarget(browserTarget, {
     watch: false,
     serviceWorker: false,
+    optimization: (optimization as unknown as JsonObject),
   });
   const serverTargetRun = await context.scheduleTarget(serverTarget, {
     watch: false,
@@ -169,7 +200,7 @@ async function _appShellBuilder(
 
     spinner = new Spinner();
     spinner.start('Generating application shell...');
-    const result =  await _renderUniversal(options, context, browserResult, serverResult);
+    const result = await _renderUniversal(options, context, browserResult, serverResult, spinner);
     spinner.succeed('Application shell generation complete.');
 
     return result;

packages/angular_devkit/build_angular/src/browser/index.ts

@@ -685,7 +685,7 @@ export function buildWebpackBrowser(
 
                   for (const [locale, outputPath] of outputPaths.entries()) {
                     try {
-                      const content = await indexHtmlGenerator.process({
+                      const { content, warnings, errors } = await indexHtmlGenerator.process({
                         baseHref: getLocaleBaseHref(i18n, locale) || options.baseHref,
                         // i18nLocale is used when Ivy is disabled
                         lang: locale || options.i18nLocale,
@@ -695,6 +695,13 @@ export function buildWebpackBrowser(
                         moduleFiles: mapEmittedFilesToFileInfo(moduleFiles),
                       });
 
+                      if (warnings.length || errors.length) {
+                        spinner.stop();
+                        warnings.forEach(m => context.logger.warn(m));
+                        errors.forEach(m => context.logger.error(m));
+                        spinner.start();
+                      }
+
                       const indexOutput = path.join(outputPath, getIndexOutputFile(options.index));
                       await mkdir(path.dirname(indexOutput), { recursive: true });
                       await writeFile(indexOutput, content);

packages/angular_devkit/build_angular/src/browser/schema.json

@@ -57,7 +57,7 @@
       "additionalProperties": false
     },
     "optimization": {
-      "description": "Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination and fonts inlining. For more information, see https://angular.io/guide/workspace-config#optimization-and-source-map-configuration.",
+      "description": "Enables optimization of the build output. Including minification of scripts and styles, tree-shaking, dead-code elimination, inlining of critical CSS and fonts inlining. For more information, see https://angular.io/guide/workspace-config#optimization-and-source-map-configuration.",
       "x-user-analytics": 16,
       "default": false,
       "oneOf": [
@@ -70,9 +70,29 @@
               "default": true
             },
             "styles": {
-              "type": "boolean",
               "description": "Enables optimization of the styles output.",
-              "default": true
+              "default": true,
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "minify": {
+                      "type": "boolean",
+                      "description": "Minify CSS definitions by removing extraneous whitespace and comments, merging identifiers and minimizing values.",
+                      "default": true
+                    },
+                    "inlineCritical": {
+                      "type": "boolean",
+                      "description": "Extract and inline critical CSS definitions to improve first paint time.",
+                      "default": false
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
             },
             "fonts": {
               "description": "Enables optimization for fonts. This requires internet access.",

packages/angular_devkit/build_angular/src/browser/specs/inline-critical-css-optimization_spec.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright Google Inc. All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { Architect } from '@angular-devkit/architect';
+import { browserBuild, createArchitect, host } from '../../test-utils';
+
+describe('Browser Builder inline critical CSS optimization', () => {
+  const target = { project: 'app', target: 'build' };
+  const overrides = {
+    optimization: {
+      scripts: false,
+      styles: {
+        minify: true,
+        inlineCritical: true,
+      },
+      fonts: false,
+    },
+  };
+
+  let architect: Architect;
+
+  beforeEach(async () => {
+    await host.initialize().toPromise();
+    architect = (await createArchitect(host.root())).architect;
+    host.writeMultipleFiles({
+      'src/styles.css': `
+        body { color: #000 }
+      `,
+    });
+  });
+
+  afterEach(async () => host.restore().toPromise());
+
+  it('works', async () => {
+    const { files } = await browserBuild(architect, host, target, overrides);
+    const html = await files['index.html'];
+    expect(html).toContain(`<link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'">`);
+    expect(html).toContain(`body{color:#000;}`);
+  });
+
+  it('works with deployUrl', async () => {
+    const { files } = await browserBuild(architect, host, target, { ...overrides, deployUrl: 'http://cdn.com/' });
+    const html = await files['index.html'];
+    expect(html).toContain(`<link rel="stylesheet" href="http://cdn.com/styles.css" media="print" onload="this.media='all'">`);
+    expect(html).toContain(`body{color:#000;}`);
+  });
+
+  it('should not inline critical css when option is disabled', async () => {
+    const { files } = await browserBuild(architect, host, target, { optimization: false });
+    const html = await files['index.html'];
+    expect(html).toContain(`<link rel="stylesheet" href="styles.css">`);
+    expect(html).not.toContain(`body{color:#000;}`);
+  });
+});

packages/angular_devkit/build_angular/src/dev-server/index.ts

@@ -107,9 +107,11 @@ export function serveWebpackBrowser(
       );
 
     // Get dev-server only options.
-    const devServerOptions = (Object.keys(options) as (keyof Schema)[])
+    type DevServerOptions = Partial<Omit<Schema,
+      'watch' | 'optimization' | 'aot' | 'sourceMap' | 'vendorChunk' | 'commonChunk' | 'baseHref' | 'progress' | 'poll' | 'verbose' | 'deployUrl'>>;
+    const devServerOptions: DevServerOptions = (Object.keys(options) as (keyof Schema)[])
       .filter(key => !devServerBuildOverriddenKeys.includes(key) && key !== 'browserTarget')
-      .reduce<Partial<Schema>>(
+      .reduce<DevServerOptions>(
         (previous, key) => ({
           ...previous,
           [key]: options[key],
@@ -288,7 +290,7 @@ export function serveWebpackBrowser(
         );
       }
 
-      if (normalizedOptimization.scripts || normalizedOptimization.styles) {
+      if (normalizedOptimization.scripts || normalizedOptimization.styles.minify) {
         logger.error(tags.stripIndents`
           ****************************************************************************************
           This is a simple server for use in testing or debugging Angular applications locally.