@rushstack/heft-web-rig 0.8.2 → 0.9.2

package/profiles/library/config/heft.json

@@ -4,32 +4,133 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/heft.schema.json",
 
+  /**
+   * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
+   * settings to be shared across multiple projects.
+   */
+  // "extends": "base-project/config/heft.json",
+
   "eventActions": [
+    // {
+    //   /**
+    //    * (Required) The kind of built-in operation that should be performed.
+    //    * The "deleteGlobs" action deletes files or folders that match the specified glob patterns.
+    //    */
+    //   "actionKind": "deleteGlobs",
+    //
+    //   /**
+    //    * (Required) The Heft stage when this action should be performed.  Note that heft.json event actions
+    //    * are scheduled after any plugin tasks have processed the event.  For example, a "compile" event action
+    //    * will be performed after the TypeScript compiler has been invoked.
+    //    *
+    //    * Options: "clean", "pre-compile", "compile", "bundle", "post-build"
+    //    */
+    //   "heftEvent": "clean",
+    //
+    //   /**
+    //    * (Required) A user-defined tag whose purpose is to allow configs to replace/delete handlers that
+    //    * were added by other configs.
+    //    */
+    //   "actionId": "my-example-action",
+    //
+    //   /**
+    //    * (Required) Glob patterns to be deleted. The paths are resolved relative to the project folder.
+    //    * Documentation for supported glob syntaxes: https://www.npmjs.com/package/fast-glob
+    //    */
+    //   "globsToDelete": [
+    //     "dist",
+    //     "lib",
+    //     "lib-esnext",
+    //     "temp"
+    //   ]
+    // },
+    //
+    // {
+    //   /**
+    //    * (Required) The kind of built-in operation that should be performed.
+    //    * The "copyFiles" action copies files that match the specified patterns.
+    //    */
+    //   "actionKind": "copyFiles",
+    //
+    //   /**
+    //    * (Required) The Heft stage when this action should be performed.  Note that heft.json event actions
+    //    * are scheduled after any plugin tasks have processed the event.  For example, a "compile" event action
+    //    * will be performed after the TypeScript compiler has been invoked.
+    //    *
+    //    * Options: "pre-compile", "compile", "bundle", "post-build"
+    //    */
+    //   "heftEvent": "pre-compile",
+    //
+    //   /**
+    //    * (Required) A user-defined tag whose purpose is to allow configs to replace/delete handlers that
+    //    * were added by other configs.
+    //    */
+    //   "actionId": "my-example-action",
+    //
+    //   /**
+    //    * (Required) An array of copy operations to run perform during the specified Heft event.
+    //    */
+    //   "copyOperations": [
+    //     {
+    //       /**
+    //        * (Required) The base folder that files will be copied from, relative to the project root.
+    //        * Settings such as "includeGlobs" and "excludeGlobs" will be resolved relative
+    //        * to this folder.
+    //        * NOTE: Assigning "sourceFolder" does not by itself select any files to be copied.
+    //        */
+    //       "sourceFolder": "src",
+    //
+    //       /**
+    //        * (Required) One or more folders that files will be copied into, relative to the project root.
+    //        * If you specify more than one destination folder, Heft will read the input files only once, using
+    //        * streams to efficiently write multiple outputs.
+    //        */
+    //       "destinationFolders": ["dist/assets"],
+    //
+    //       /**
+    //        * If specified, this option recursively scans all folders under "sourceFolder" and includes any files
+    //        * that match the specified extensions.  (If "fileExtensions" and "includeGlobs" are both
+    //        * specified, their selections are added together.)
+    //        */
+    //       "fileExtensions": [".jpg", ".png"],
+    //
+    //       /**
+    //        * A list of glob patterns that select files to be copied.  The paths are resolved relative
+    //        * to "sourceFolder".
+    //        * Documentation for supported glob syntaxes: https://www.npmjs.com/package/fast-glob
+    //        */
+    //       "includeGlobs": ["assets/*.md"],
+    //
+    //       /**
+    //        * A list of glob patterns that exclude files/folders from being copied.  The paths are resolved relative
+    //        * to "sourceFolder".  These exclusions eliminate items that were selected by the "includeGlobs"
+    //        * or "fileExtensions" setting.
+    //        */
+    //       "excludeGlobs": [],
+    //
+    //       /**
+    //        * Normally, when files are selected under a child folder, a corresponding folder will be created in
+    //        * the destination folder.  Specify flatten=true to discard the source path and copy all matching files
+    //        * to the same folder.  If two files have the same name an error will be reported.
+    //        * The default value is false.
+    //        */
+    //       "flatten": false,
+    //
+    //       /**
+    //        * If true, filesystem hard links will be created instead of copying the file.  Depending on the
+    //        * operating system, this may be faster. (But note that it may cause unexpected behavior if a tool
+    //        * modifies the link.)  The default value is false.
+    //        */
+    //       "hardlink": false
+    //     }
+    //   ]
+    // }
+
     {
-      /**
-       * The kind of built-in operation that should be performed.
-       * The "deleteGlobs" action deletes files or folders that match the
-       * specified glob patterns.
-       */
       "actionKind": "deleteGlobs",
-
-      /**
-       * The stage of the Heft run during which this action should occur. Note that actions specified in heft.json
-       * occur at the end of the stage of the Heft run.
-       */
       "heftEvent": "clean",
-
-      /**
-       * A user-defined tag whose purpose is to allow configs to replace/delete handlers that were added by other
-       * configs.
-       */
       "actionId": "defaultClean",
-
-      /**
-       * Glob patterns to be deleted. The paths are resolved relative to the project folder.
-       * Recommend exactly matching with "projectOutputFolderNames" in rush-project.json.
-       */
-      "globsToDelete": ["dist", "lib", "lib-commonjs", "temp"]
+      "globsToDelete": ["dist", "lib", "lib-amd", "lib-commonjs", "lib-es6", "temp"]
     }
   ],
 
@@ -37,22 +138,19 @@
    * The list of Heft plugins to be loaded.
    */
   "heftPlugins": [
-    {
-      /**
-       * The path to the plugin package.
-       */
-      "plugin": "@rushstack/heft-webpack4-plugin"
-
-      /**
-       * An optional object that provides additional settings that may be defined by the plugin.
-       */
-      // "options": { }
-    },
-    {
-      "plugin": "@rushstack/heft-jest-plugin"
-    },
-    {
-      "plugin": "@rushstack/heft-sass-plugin"
-    }
+    // {
+    //  /**
+    //   * The path to the plugin package.
+    //   */
+    //  "plugin": "path/to/my-plugin",
+    //
+    //  /**
+    //   * An optional object that provides additional settings that may be defined by the plugin.
+    //   */
+    //  // "options": { }
+    // }
+    { "plugin": "@rushstack/heft-jest-plugin" },
+    { "plugin": "@rushstack/heft-sass-plugin" },
+    { "plugin": "@rushstack/heft-webpack5-plugin" }
   ]
 }

package/profiles/library/config/rush-project.json

@@ -2,11 +2,11 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["dist", "lib", "lib-commonjs", "temp"]
+      "outputFolderNames": ["dist", "lib", "lib-amd", "lib-commonjs", "lib-es6", "temp"]
     },
     {
       "operationName": "build",
-      "outputFolderNames": ["dist", "lib", "lib-commonjs", "temp"]
+      "outputFolderNames": ["dist", "lib", "lib-amd", "lib-commonjs", "lib-es6", "temp"]
     }
   ]
 }

package/profiles/library/config/sass.json

@@ -1,47 +1,65 @@
 /**
- * Configures the Sass Typings plugin for the Heft build system.
+ * Configuration for @rushstack/heft-sass-plugin
  *
  * This optional additional file customizes Sass parsing, module resolution, and emitting of
- * typings files for the Typescript compiler.
+ * Typescript .d.ts files.
  */
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/heft/sass.schema.json"
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft-sass-plugin.schema.json",
 
   /**
-   * Source code root directory.
-   * This is where .css, .sass, and .scss files will be searched for to generate typings.
+   * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
+   * settings to be shared across multiple projects.
    */
-  // "srcFolder": "src",
+  // "extends": "base-project/config/serve-command.json",
+
+  /**
+   * The root directory for project source code.
+   *
+   * Default value: "src/"
+   */
+  // "srcFolder": "src/",
 
   /**
    * Output directory for generated Sass typings.
+   *
+   * Default value: "temp/sass-ts/"
+   */
+  // "generatedTsFolder": "temp/sass-ts/",
+
+  /**
+   * Determines whether export values are wrapped in a default property, or not.
+   *
+   * Default value: true
    */
-  // "generatedTsFolder": "temp/sass-ts",
+  // "exportAsDefault": false,
 
   /**
-   * Determines if export values are wrapped in a default property, or not.
+   * If specified, folders where compiled CSS files will be emitted to. They will be named by appending
+   * ".css" to the source file name for ease of reference translation.
+   *
+   * Default value: undefined
    */
-  // "exportAsDefault": true,
+  // "cssOutputFolders": ["lib", "lib-commonjs"],
 
   /**
    * Files with these extensions will pass through the Sass transpiler for typings generation.
+   *
+   * Default value: [".sass", ".scss", ".css"]
    */
-  // "fileExtensions": [
-  //   ".sass",
-  //   ".scss",
-  //   ".css
-  // ],
+  "fileExtensions": [".sass", ".scss"]
 
   /**
-   * A list of paths used when resolving Sass imports.
+   * A list of paths used when resolving Sass imports.  The paths should be relative to the project root.
+   *
+   * Default value: ["node_modules", "src"]
    */
-  // "importIncludePaths": [
-  //   "node_modules",
-  //   "src"
-  // ],
+  // "importIncludePaths": ["node_modules", "src"],
 
   /**
    * A list of file paths relative to the "src" folder that should be excluded from typings generation.
+   *
+   * Default value: undefined
    */
   // "excludeFiles": []
 }

package/profiles/library/config/typescript.json

@@ -4,24 +4,45 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/typescript.schema.json",
 
+  /**
+   * Optionally specifies another JSON config file that this file extends from. This provides a way for standard
+   * settings to be shared across multiple projects.
+   */
+  // "extends": "base-project/config/typescript.json",
+
   /**
    * If provided, emit these module kinds in addition to the modules specified in the tsconfig.
    * Note that this option only applies to the main tsconfig.json configuration.
    */
   "additionalModuleKindsToEmit": [
+    // {
+    //   /**
+    //    * (Required) Must be one of "commonjs", "amd", "umd", "system", "es2015", "esnext"
+    //    */
+    //  "moduleKind": "amd",
+    //
+    //   /**
+    //    * (Required) The name of the folder where the output will be written.
+    //    */
+    //    "outFolderName": "lib-amd"
+    // }
+
     {
-      /**
-       * (Required) Must be one of "commonjs", "amd", "umd", "system", "es2015", "esnext"
-       */
       "moduleKind": "commonjs",
-
-      /**
-       * (Required) The name of the folder where the output will be written.
-       */
       "outFolderName": "lib-commonjs"
     }
   ],
 
+  /**
+   * If true, emit CommonJS module output to the folder specified in the tsconfig "outDir" compiler option with the .cjs extension alongside (or instead of, if TSConfig specifies CommonJS) the default compilation output.
+   */
+  // "emitCjsExtensionForCommonJS": true,
+
+  /**
+   * If true, emit ESNext module output to the folder specified in the tsconfig "outDir" compiler option with the .mjs extension alongside (or instead of, if TSConfig specifies ESNext) the default compilation output.
+   */
+  // "emitMjsExtensionForESModule": true,
+
   /**
    * Specifies the intermediary folder that tests will use.  Because Jest uses the
    * Node.js runtime to execute tests, the module format must be CommonJS.
@@ -42,13 +63,36 @@
   // "maxWriteParallelism": 50,
 
   /**
-   * Describes the way files should be statically coped from src to TS output folders
+   * Configures additional file types that should be copied into the TypeScript compiler's emit folders, for example
+   * so that these files can be resolved by import statements.
    */
   "staticAssetsToCopy": {
     /**
      * File extensions that should be copied from the src folder to the destination folder(s).
      */
-    "fileExtensions": [".json"]
+    "fileExtensions": [
+      ".aac",
+      ".css",
+      ".eot",
+      ".gif",
+      ".jpeg",
+      ".jpg",
+      ".json",
+      ".m4a",
+      ".mp3",
+      ".mp4",
+      ".oga",
+      ".otf",
+      ".png",
+      ".scss",
+      ".svg",
+      ".ttf",
+      ".wav",
+      ".webm",
+      ".webp",
+      ".woff",
+      ".woff2"
+    ]
 
     /**
      * Glob patterns that should be explicitly included.

package/profiles/library/tsconfig-base.json

@@ -14,9 +14,11 @@
     "inlineSources": true,
     "experimentalDecorators": true,
     "strict": true,
+    "useUnknownInCatchVariables": false,
     "esModuleInterop": true,
     "noEmitOnError": false,
     "allowUnreachableCode": false,
+    "importHelpers": true,
 
     "types": [],
 

package/profiles/library/webpack-base.config.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const path = require('path');
+const createWebpackConfigCommon = require('../../shared/webpack-base.config');
+
+module.exports = function createWebpackConfig({ env, argv, projectRoot, configOverride }) {
+  // Example: "@my-company/my-library"
+  const packageName = require(path.join(projectRoot, 'package.json')).name;
+  // Example: "my-library"
+  const packageNameWithoutScope = packageName.split('/').pop();
+
+  // Documentation: https://webpack.js.org/configuration/
+  const libraryOverrides = {
+    target: ['web', 'es5'],
+    entry: {
+      // Rush Stack convention is that the entry point for libraries is "src/index.ts"
+      // whereas the entry point for apps is "src/start.ts"
+      [packageNameWithoutScope]: path.resolve(projectRoot, 'lib', 'index.js')
+    },
+    output: {
+      // For libraries, the filename is unhashed so that the package.json "main" field can refer to it
+      filename: `[name].js`,
+      library: {
+        // Use the full package name as the module-id name for AMD
+        amd: packageName
+      },
+      libraryTarget: 'umd',
+
+      // https://webpack.js.org/configuration/output/#outputlibraryumdnameddefine
+      // Give the amd module a globally unique id so that non AMD aware bundlers can concatenate the module
+      umdNamedDefine: true,
+
+      // From: https://webpack.js.org/configuration/output/#outputglobalobject
+      // To make UMD build available on both browsers and Node.js, set output.globalObject option to 'this'
+      globalObject: 'this'
+    },
+    devtool: 'source-map'
+  };
+
+  return createWebpackConfigCommon({
+    env: env,
+    argv: argv,
+    projectRoot: projectRoot,
+    configOverride: createWebpackConfigCommon.merge(libraryOverrides, configOverride)
+  });
+};