build(docs-infra): switch the `generate-stackblitz/zips` scripts to ESM (#42921)

Switch the JS scripts used for generating StackBlitz projects and zips
from CommonJS to ESM format. This is necessary for upgrading the
`globby` dependency to [version 12.0.0][1] in a subsequent commit.

[1]: https://github.com/sindresorhus/globby/releases/v12.0.0

PR Close #42921

aio/package.json

@@ -63,8 +63,8 @@
     "boilerplate:add": "node ./tools/examples/example-boilerplate add",
     "boilerplate:remove": "node ./tools/examples/example-boilerplate remove",
     "boilerplate:test": "node tools/examples/test.js",
-    "generate-stackblitz": "node ./tools/stackblitz-builder/generateStackblitz",
+    "generate-stackblitz": "node ./tools/stackblitz-builder/generateStackblitz.mjs",
-    "generate-zips": "node ./tools/example-zipper/generateZips",
+    "generate-zips": "node ./tools/example-zipper/generateZips.mjs",
     "create-example": "node ./tools/examples/create-example.js",
     "build-404-page": "node scripts/build-404-page",
     "update-webdriver": "node ../scripts/webdriver-manager-update.js",

aio/tools/example-zipper/README.md

@@ -5,7 +5,7 @@ These zip files are generated by the utility in this folder.
 
 ## Example zipper
 
-The `exampleZipper.js` tool is very similar to the Stackblitz's `builder.js`.
+The `exampleZipper.mjs` tool is very similar to the Stackblitz's `builder.mjs`.
 The latter creates an HTML file with all the examples' files and the former creates a zip file instead.
 They both use the `stackblitz.json` file to flag an example as something to stackblitz or zip.
 For example:
@@ -35,7 +35,7 @@ These example types have separate boilerplate directories with the files that ar
 There are appropriate `package.json` files for each type of example in the boilerplate directories.
 If there is no special `package.json` file for an example type, the one from the `cli` boilerplate directory will be used instead.
 
-The `exampleZipper.js` won't include any `System.js` related files for CLI-based projects.
+The `exampleZipper.mjs` won't include any `System.js` related files for CLI-based projects.
 
 ## The zipper.json
 
@@ -46,7 +46,7 @@ In those cases, you can create a `zipper.json` file with the same syntax. It wil
 
 ## Executing the zip generation
 
-`generateZips.js` will create a zip for each `stackblitz.json`  or `zipper.json` it finds.
+`generateZips.mjs` will create a zip for each `stackblitz.json`  or `zipper.json` it finds.
 
 Where? At `src/generated/zips/`.
 

aio/tools/example-zipper/exampleZipper.mjs

@@ -1,16 +1,16 @@
-'use strict';
-
 // Canonical path provides a consistent path (i.e. always forward slashes) across different OSes
-const path = require('canonical-path');
+import archiver from 'archiver';
-const archiver = require('archiver');
+import path from 'canonical-path';
-const fs = require('fs-extra');
+import fs from 'fs-extra';
-const globby = require('globby');
+import globby from 'globby';
+import {fileURLToPath} from 'url';
 
-const regionExtractor = require('../transforms/examples-package/services/region-parser');
+import regionExtractor from '../transforms/examples-package/services/region-parser.js';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const EXAMPLE_CONFIG_NAME = 'example-config.json';
 
-class ExampleZipper {
+export class ExampleZipper {
   constructor(sourceDirName, outputDirName) {
     this.examplesPackageJson = path.join(__dirname, '../examples/shared/package.json');
     this.examplesSystemjsConfig = path.join(__dirname, '../examples/shared/boilerplate/systemjs/src/systemjs.config.js');
@@ -46,12 +46,16 @@ class ExampleZipper {
   _getExampleType(sourceFolder) {
     const filePath = path.join(sourceFolder, EXAMPLE_CONFIG_NAME);
     try {
-      return require(filePath, 'utf-8').projectType || 'cli';
+      return this._loadJson(filePath).projectType || 'cli';
     } catch (err) { // empty file, so it is cli
       return 'cli';
     }
   }
 
+  _loadJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  }
+
   // rename a custom main.ts or index.html file
   _renameFile(file, exampleType) {
     if (/src\/main[-.]\w+\.ts$/.test(file) && exampleType !== 'universal') {
@@ -66,7 +70,7 @@ class ExampleZipper {
   }
 
   _zipExample(configFileName, sourceDirName, outputDirName) {
-    let json = require(configFileName, 'utf-8');
+    let json = this._loadJson(configFileName);
     const basePath = json.basePath || '';
     const jsonFileName = configFileName.replace(/^.*[\\\/]/, '');
     let relativeDirName = path.dirname(path.relative(sourceDirName, configFileName));
@@ -176,5 +180,3 @@ class ExampleZipper {
     zip.finalize();
   }
 }
-
-module.exports = ExampleZipper;

aio/tools/example-zipper/generateZips.mjs

@@ -1,6 +1,8 @@
-const ExampleZipper = require('./exampleZipper');
+import path from 'canonical-path';
-const path = require('canonical-path');
+import {fileURLToPath} from 'url';
+import {ExampleZipper} from './exampleZipper.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const EXAMPLES_PATH = path.join(__dirname, '../../content/examples');
 const ZIPS_PATH = path.join(__dirname, '../../src/generated/zips');
 

aio/tools/stackblitz-builder/README.md

@@ -4,11 +4,11 @@
 In AIO we use it to share one or more runnable versions of our examples.
 
 Stackblitz can be used both on a separate page and in an embedded form.
-* `generateStackblitz.js` - executes each of the StackblitzBuilder to generate a stackblitz file for each example.
+* `generateStackblitz.mjs` - executes each of the StackblitzBuilder to generate a stackblitz file for each example.
 
 ## Stackblitz generation
 
-Both forms are created within `builder.js`.
+Both forms are created within `builder.mjs`.
 How is a stackblitz created?
 What is the process from a directory with files to a link with a stackblitz.
 
@@ -17,13 +17,13 @@ It contains an `<input>` element for each file we need in the stackblitz.
 
 The form will be submitted on load, so you can either double click the HTML file or open it with an anchor tag to open the stackblitz.
 
-So the `builder.js` job is to get all the needed files from an example and build this HTML file for you.
+So the `builder.mjs` job is to get all the needed files from an example and build this HTML file for you.
 
 ## Customizing the generation per example basis
 
 How does this tool know what is an example and what is not?
 It will look for all folders containing a `stackblitz.json` file.
-If found, all files within the folder and subfolders will be used in the stackblitz, with a few generic exceptions that you can find at `builder.js`.
+If found, all files within the folder and subfolders will be used in the stackblitz, with a few generic exceptions that you can find at `builder.mjs`.
 
 You can use the `stackblitz.json` to customize the stackblitz generation.
 For example:
@@ -44,7 +44,7 @@ Here you can specify a description for the stackblitz, some tags and also a file
 
 ## Executing the stackblitz generation
 
-`generateStackblitz.js` will create a stackblitz for each `stackblitz.json` it finds.
+`generateStackblitz.mjs` will create a stackblitz for each `stackblitz.json` it finds.
 
 Where?
 At `src/generated/live-examples/`.

aio/tools/stackblitz-builder/builder.mjs

@@ -1,15 +1,16 @@
-'use strict';
-
 // Canonical path provides a consistent path (i.e. always forward slashes) across different OSes
-const path = require('canonical-path');
+import path from 'canonical-path';
-const fs = require('fs-extra');
+import fs from 'fs-extra';
-const globby = require('globby');
+import globby from 'globby';
-const jsdom = require('jsdom');
+import jsdom from 'jsdom';
-const json5 = require('json5');
+import json5 from 'json5';
+import {fileURLToPath} from 'url';
 
-const regionExtractor = require('../transforms/examples-package/services/region-parser');
+import regionExtractor from '../transforms/examples-package/services/region-parser.js';
 
-class StackblitzBuilder {
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class StackblitzBuilder {
   constructor(basePath, destPath) {
     this.basePath = basePath;
     this.destPath = destPath;
@@ -64,7 +65,9 @@ class StackblitzBuilder {
   _getBoilerplatePackageJson(exampleType) {
     if (!this._boilerplatePackageJsons.hasOwnProperty(exampleType)) {
       const pkgJsonPath = `${__dirname}/../examples/shared/boilerplate/${exampleType}/package.json`;
-      this._boilerplatePackageJsons[exampleType] = fs.existsSync(pkgJsonPath) ? require(pkgJsonPath) : null;
+      this._boilerplatePackageJsons[exampleType] = fs.existsSync(pkgJsonPath)
+          ? JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+          : null;
     }
 
     return this._boilerplatePackageJsons[exampleType];
@@ -341,5 +344,3 @@ class StackblitzBuilder {
     }
   }
 }
-
-module.exports = StackblitzBuilder;

aio/tools/stackblitz-builder/generateStackblitz.js

@@ -1,8 +0,0 @@
-const path = require('path');
-const StackblitzBuilder = require('./builder');
-
-const EXAMPLES_PATH = path.join(__dirname, '../../content/examples');
-const LIVE_EXAMPLES_PATH = path.join(__dirname, '../../src/generated/live-examples');
-
-new StackblitzBuilder(EXAMPLES_PATH, LIVE_EXAMPLES_PATH).build();
-

aio/tools/stackblitz-builder/generateStackblitz.mjs

@@ -0,0 +1,9 @@
+import {dirname, join} from 'path';
+import {fileURLToPath} from 'url';
+import {StackblitzBuilder} from './builder.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const EXAMPLES_PATH = join(__dirname, '../../content/examples');
+const LIVE_EXAMPLES_PATH = join(__dirname, '../../src/generated/live-examples');
+
+new StackblitzBuilder(EXAMPLES_PATH, LIVE_EXAMPLES_PATH).build();