@rushstack/heft-web-rig 0.8.2 → 0.9.2

package/README.md

@@ -4,7 +4,11 @@ A rig package for web projects that build using [Heft](https://www.npmjs.com/pac
 build system.  To learn more about rig packages, consult the
 [@rushstack/rig-package](https://www.npmjs.com/package/@rushstack/rig-package) documentation.
 
-This rig contains a single profile: `library`
+This rig provides the following profiles:
+
+- [app](./profiles/app/): For applications that get bundled using Webpack.
+- [library](./profiles/library/): For creating library packages to be consumed by other web projects.  ***Also use this profile for a library meant to be used by both Node.js and web apps.***
+
 
 To enable it, add a **rig.json** file to your project, as shown below:
 

package/package.json

@@ -1,30 +1,47 @@
 {
-	"name": "@rushstack/heft-web-rig",
-	"version": "0.8.2",
-	"description": "A rig package for web browser projects that build using Heft",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/microsoft/rushstack.git",
-		"directory": "rigs/heft-web-rig"
-	},
-	"peerDependencies": {
-		"@rushstack/heft": "^0.44.2"
-	},
-	"dependencies": {
-		"@microsoft/api-extractor": "7.19.4",
-		"@rushstack/heft-jest-plugin": "0.2.2",
-		"@rushstack/heft-sass-plugin": "0.3.6",
-		"@rushstack/heft-webpack4-plugin": "0.3.32",
-		"eslint": "~8.7.0",
-		"jest-environment-jsdom": "~27.4.2",
-		"typescript": "~4.5.2"
-	},
-	"devDependencies": {
-		"@rushstack/heft": "0.44.2"
-	},
-	"scripts": {
-		"build": "",
-		"_phase:build": ""
-	}
-}
+  "name": "@rushstack/heft-web-rig",
+  "version": "0.9.2",
+  "description": "A rig package for web browser projects that build using Heft",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/rushstack.git",
+    "directory": "rigs/heft-web-rig"
+  },
+  "peerDependencies": {
+    "@rushstack/heft": "^0.44.4"
+  },
+  "dependencies": {
+    "@microsoft/api-extractor": "7.19.5",
+    "@rushstack/heft-jest-plugin": "0.2.5",
+    "@rushstack/heft-sass-plugin": "0.3.9",
+    "@rushstack/heft-webpack5-plugin": "0.5.2",
+    "autoprefixer": "~10.4.2",
+    "css-loader": "~6.6.0",
+    "css-minimizer-webpack-plugin": "~3.4.1",
+    "eslint": "~8.7.0",
+    "html-webpack-plugin": "~5.5.0",
+    "jest-environment-jsdom": "~27.4.2",
+    "mini-css-extract-plugin": "~2.5.3",
+    "postcss-loader": "~6.2.1",
+    "postcss": "~8.4.6",
+    "sass-loader": "~12.4.0",
+    "sass": "~1.49.7",
+    "source-map-loader": "~3.0.1",
+    "style-loader": "~3.3.1",
+    "terser-webpack-plugin": "~5.3.1",
+    "typescript": "~4.5.5",
+    "url-loader": "~4.1.1",
+    "webpack-bundle-analyzer": "~4.5.0",
+    "webpack-merge": "~5.8.0",
+    "webpack": "~5.68.0"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "0.44.4"
+  },
+  "scripts": {
+    "build": "",
+    "_phase:build": ""
+  },
+  "readme": "## @rushstack/heft-web-rig\n\nA rig package for web projects that build using [Heft](https://www.npmjs.com/package/@rushstack/heft)\nbuild system.  To learn more about rig packages, consult the\n[@rushstack/rig-package](https://www.npmjs.com/package/@rushstack/rig-package) documentation.\n\nThis rig provides the following profiles:\n\n- [app](./profiles/app/): For applications that get bundled using Webpack.\n- [library](./profiles/library/): For creating library packages to be consumed by other web projects.  ***Also use this profile for a library meant to be used by both Node.js and web apps.***\n\n\nTo enable it, add a **rig.json** file to your project, as shown below:\n\n**config/rig.json**\n```js\n{\n  \"$schema\": \"https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json\",\n\n  \"rigPackageName\": \"@rushstack/heft-web-rig\",\n  \"rigProfile\": \"library\"\n}\n```\n\nThe config files provided by this rig profile can be found in the [heft-web-rig/profiles/library](\nhttps://github.com/microsoft/rushstack/tree/master/rigs/heft-web-rig/profiles/library) source folder.\n\n\n## Links\n\n- [CHANGELOG.md](\n  https://github.com/microsoft/rushstack/blob/master/rigs/heft-web-rig/CHANGELOG.md) - Find\n  out what's new in the latest version\n\n`@rushstack/heft-web-rig` is part of the [Rush Stack](https://rushstack.io/) family of projects.\n"
+}

package/profiles/app/config/heft.json

@@ -0,0 +1,156 @@
+/**
+ * Defines configuration used by core Heft.
+ */
+{
+  "$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
+    //     }
+    //   ]
+    // }
+
+    {
+      "actionKind": "deleteGlobs",
+      "heftEvent": "clean",
+      "actionId": "defaultClean",
+      "globsToDelete": ["dist", "lib", "lib-amd", "lib-commonjs", "lib-es6", "temp"]
+    }
+  ],
+
+  /**
+   * The list of Heft plugins to be loaded.
+   */
+  "heftPlugins": [
+    // {
+    //  /**
+    //   * 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/app/config/jest.config.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@rushstack/heft-jest-plugin/includes/jest-shared.config.json",
+
+  "testEnvironment": "jest-environment-jsdom"
+}

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

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

package/profiles/app/config/sass.json

@@ -0,0 +1,65 @@
+/**
+ * Configuration for @rushstack/heft-sass-plugin
+ *
+ * This optional additional file customizes Sass parsing, module resolution, and emitting of
+ * Typescript .d.ts files.
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/heft-sass-plugin.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/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
+   */
+  // "exportAsDefault": false,
+
+  /**
+   * 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
+   */
+  // "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"]
+
+  /**
+   * 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"],
+
+  /**
+   * A list of file paths relative to the "src" folder that should be excluded from typings generation.
+   *
+   * Default value: undefined
+   */
+  // "excludeFiles": []
+}

package/profiles/app/config/typescript.json

@@ -0,0 +1,112 @@
+/**
+ * Configures the TypeScript plugin for Heft.  This plugin also manages linting.
+ */
+{
+  "$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"
+    // }
+
+    {
+      "moduleKind": "commonjs",
+      "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.
+   *
+   * The default value is "lib".
+   */
+  "emitFolderNameForTests": "lib-commonjs",
+
+  /**
+   * If set to "true", the TSlint task will not be invoked.
+   */
+  // "disableTslint": true,
+
+  /**
+   * Set this to change the maximum number of file handles that will be opened concurrently for writing.
+   * The default is 50.
+   */
+  // "maxWriteParallelism": 50,
+
+  /**
+   * 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": [
+      ".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.
+     */
+    // "includeGlobs": [
+    //   "some/path/*.js"
+    // ],
+
+    /**
+     * Glob patterns that should be explicitly excluded. This takes precedence over globs listed
+     * in "includeGlobs" and files that match the file extensions provided in "fileExtensions".
+     */
+    // "excludeGlobs": [
+    //   "some/path/*.css"
+    // ]
+  }
+}

package/profiles/app/tsconfig-base.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+
+  "compilerOptions": {
+    "outDir": "../../../../../lib",
+    "rootDir": "../../../../../src",
+    "rootDirs": ["../../../../../src", "../../../../../temp/sass-ts"],
+
+    "forceConsistentCasingInFileNames": true,
+    "jsx": "react",
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "experimentalDecorators": true,
+    "strict": true,
+    "useUnknownInCatchVariables": false,
+    "esModuleInterop": true,
+    "noEmitOnError": false,
+    "allowUnreachableCode": false,
+    "importHelpers": true,
+
+    "types": [],
+
+    "module": "esnext",
+    "moduleResolution": "node",
+    "target": "es5",
+    "lib": ["es5", "scripthost", "es2015.collection", "es2015.promise", "es2015.iterable", "dom"]
+  },
+  "include": ["../../../../../src/**/*.ts", "../../../../../src/**/*.tsx"]
+}

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

@@ -0,0 +1,38 @@
+'use strict';
+
+const path = require('path');
+const HtmlWebpackPlugin = require('html-webpack-plugin');
+const createWebpackConfigCommon = require('../../shared/webpack-base.config');
+
+module.exports = function createWebpackConfig({ env, argv, projectRoot, configOverride }) {
+  // Documentation: https://webpack.js.org/configuration/
+  const applicationOverrides = {
+    target: ['web', 'es5'],
+    entry: {
+      app: path.resolve(projectRoot, 'lib', 'start.js')
+    },
+    optimization: {
+      splitChunks: {
+        chunks: 'all'
+      }
+    },
+    plugins: [
+      // NOTE: If your project's webpack.config.js provides its own "HtmlWebpackPlugin" configuration,
+      // it will replace the default definition here.  This replacement is implemented
+      // using mergeWithCustomize() in shared/webpack-base.config.js
+
+      // See here for documentation: https://github.com/jantimon/html-webpack-plugin
+      new HtmlWebpackPlugin({
+        filename: 'index.html',
+        template: path.resolve(projectRoot, 'assets', 'index.html')
+      })
+    ]
+  };
+
+  return createWebpackConfigCommon({
+    env: env,
+    argv: argv,
+    projectRoot: projectRoot,
+    configOverride: createWebpackConfigCommon.merge(applicationOverrides, configOverride)
+  });
+};

package/profiles/library/config/api-extractor-task.json

@@ -7,6 +7,12 @@
 {
   "$schema": "https://developer.microsoft.com/json-schemas/heft/api-extractor-task.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/api-extractor-task.json",
+
   /**
    * If set to true, use the project's TypeScript compiler version for API Extractor's
    * analysis. API Extractor's included TypeScript compiler can generally correctly